---
sidebar_position: 3
---

import { Note, Important, SectionTitle, styles, ElementNavigator } from '@site/src/components/documentation';

# Installation Guide

<div className={styles.documentationPage}>

This guide will walk you through the installation process for Cleanuparr. Cleanuparr can be installed in several ways depending on your preference and system configuration.

<ElementNavigator />

<Note>
For most users, we recommend the Docker installation method as it provides the most consistent experience across all platforms.
</Note> 

## Table of Contents

- [Docker Installation (Recommended)](#docker-installation-recommended)
  - [Docker Run Method](#docker-run)
  - [Docker Compose Method](#docker-compose)
- [Unraid](#unraid)
- [Windows Installation](#windows-installation)
  - [Windows Installer](#windows-installer)
  - [Windows Portable](#windows-portable)
- [macOS Installation](#macos-installation)
  - [macOS Installer](#macos-installer)
  - [macOS Portable](#macos-portable)
- [Linux Installation](#linux-installation)
- [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker)
- [Post Installation](#post-installation)
 
---

<div className={styles.section}>

<SectionTitle>Docker Installation (Recommended)</SectionTitle>

Docker is the preferred installation method as it ensures all dependencies are correctly installed and provides consistent behavior across all platforms.

### Docker Run

The simplest way to run Cleanuparr is with a single Docker command:

```bash
docker run -d --name cleanuparr \
  --restart unless-stopped \
  -p 11011:11011 \
  -v /path/to/config:/config \
  -e PORT=11011 \
  -e BASE_PATH= \
  -e PUID=1000 \
  -e PGID=1000 \
  -e UMASK=022 \
  -e TZ=Etc/UTC \
  ghcr.io/cleanuparr/cleanuparr:latest
```

### Docker Compose

For easier management, create a `docker-compose.yml` file:

#### Option 1: GitHub Container Registry
```yaml
services:
  cleanuparr:
    image: ghcr.io/cleanuparr/cleanuparr:latest
    container_name: cleanuparr
    restart: unless-stopped
    ports:
      - "11011:11011"
    volumes:
      - /path/to/config:/config
      # Mount your downloads directory if needed
      - /path/to/downloads:/downloads
    environment:
      - PORT=11011
      - BASE_PATH=
      - PUID=1000
      - PGID=1000
      - UMASK=022
      - TZ=Etc/UTC
    # Health check configuration
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:11011/health"]
      interval: 30s        # Check every 30 seconds
      timeout: 10s         # Allow up to 10 seconds for response
      start_period: 30s    # Wait 30 seconds before first check
      retries: 3           # Mark unhealthy after 3 consecutive failures
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | 11011 | Port for the web interface |
| `BIND_ADDRESS` | 0.0.0.0 | IP address to bind to |
| `BASE_PATH` | *(empty)* | Base path for reverse proxy setups ([examples](#example-configurations)) |
| `PUID` | 1000 | User ID for file permissions |
| `PGID` | 1000 | Group ID for file permissions |
| `UMASK` | 022 | File creation mask |
| `TZ` | Etc/UTC | Timezone setting |

### Volume Mounts

| Container Path | Description |
|----------------|-------------|
| `/config` | Configuration files, log files and database |
| `/downloads` | (Optional) Mount your downloads directory if using [Unlinked download settings](/docs/configuration/download-cleaner/?unlinked-download-settings) |

<Note>
Replace `/path/to/config` with your desired configuration directory path on the host system.
</Note>

</div>

<div className={styles.section}>

<SectionTitle>Unraid</SectionTitle>

Use the Unraid template available in the Community Applications plugin. If the template is not yet available, you can manually add using the above Docker Compose configuration or use this guide to create a custom template:

1. Download the template from here: https://github.com/Cleanuparr/unraid/blob/main/templates/Cleanuparr.xml
2. Rename the downloaded file to 'my-cleanuparr.xml'
3. Drop it in the `/boot/config/plugins/dockerMan/templates-user/` folder of your Unraid machine
4. Go to the Docker tab of the Unraid webui
5. Click on Add Container
6. From the `Template` dropdown menu, select `cleanuparr`
7. Set the repository to `ghcr.io/cleanuparr/cleanuparr:latest`
8. Most other settings can be left at default, with the exception of the downloads folder which should be mapped to where your *arr stack / torrent client downloads its files to

</div>

<div className={styles.section}>

<SectionTitle>Windows Installation</SectionTitle>

### Windows Installer

The easiest way to install Cleanuparr on Windows is using the provided installer.

#### Installation Steps
1. Download the Windows installer (`.exe`) from the [GitHub Releases](https://github.com/Cleanuparr/Cleanuparr/releases) page
2. Double-click the downloaded `.exe` file to start installation
3. **Important**: When Windows Defender SmartScreen appears, click "More info" and then "Run anyway"
4. Follow the on-screen instructions to complete installation
5. Cleanuparr will be installed as a Windows service and start automatically

#### Default Configuration
- **Web Interface**: `http://localhost:11011`
- **Service Name**: Cleanuparr
- **Installation Directory**: `C:\Program Files\Cleanuparr\`
- **Configuration**: `C:\ProgramFiles\Cleanuparr\config\`

<Note>
To change the port or base path, see [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker).
</Note>

### Windows Portable

For users who prefer a portable installation:

1. Download the `Cleanuparr-{version}-win-amd64.zip` from [GitHub Releases](https://github.com/Cleanuparr/Cleanuparr/releases)
2. Extract the zip file to your desired directory (e.g., `C:\Tools\Cleanuparr\`)
3. Run `Cleanuparr.exe` to start the application
4. Access the web interface at `http://localhost:11011`

<Note>
The portable version requires manual startup and doesn't install as a Windows service. To change the port or base path, see [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker).
</Note>

</div>

<div className={styles.section}>

<SectionTitle>macOS Installation</SectionTitle>

### macOS Installer

Cleanuparr provides native macOS installers for both Intel and Apple Silicon Macs.

#### Installation Steps
1. Download the appropriate `.pkg` installer from [GitHub Releases](https://github.com/Cleanuparr/Cleanuparr/releases):
   - `Cleanuparr-{version}-macos-intel.pkg` for Intel Macs
   - `Cleanuparr-{version}-macos-arm64.pkg` for Apple Silicon Macs
2. Double-click the downloaded `.pkg` file
3. When macOS shows a security warning, go to **System Settings → Privacy & Security**
4. Scroll down and click **"Open Anyway"** to proceed with installation
5. Follow the installation prompts
6. Cleanuparr will be installed as a system service and start automatically

#### Default Configuration
- **Web Interface**: `http://localhost:11011`
- **Application**: `/Applications/Cleanuparr.app`
- **Configuration**: `/Applications/Cleanuparr.app/Contents/MacOS/config/`
- **Service**: Managed by `launchd`

<Important>
macOS will show security warnings for unsigned applications. This is normal - click "Open Anyway" in System Settings to proceed.
</Important>

<Note>
To change the port or base path, see [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker).
</Note>

### macOS Portable

For users who prefer a portable installation:

1. Download the appropriate zip file from [GitHub Releases](https://github.com/Cleanuparr/Cleanuparr/releases):
   - `Cleanuparr-{version}-osx-amd64.zip` for Intel Macs
   - `Cleanuparr-{version}-osx-arm64.zip` for Apple Silicon Macs
2. Extract the zip file to your desired directory
3. Open Terminal and navigate to the extracted directory
4. Make the binary executable: `chmod +x Cleanuparr`
5. Run: `./Cleanuparr`
6. Access the web interface at `http://localhost:11011`

<Note>
To change the port or base path, see [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker).
</Note>

</div>

<div className={styles.section}>

<SectionTitle>Linux Installation</SectionTitle>

Linux users can use the portable executables, as we don't provide distribution-specific packages.

### Portable Installation

1. Download the appropriate zip file from [GitHub Releases](https://github.com/Cleanuparr/Cleanuparr/releases):
   - `Cleanuparr-{version}-linux-amd64.zip` for x86_64 systems
   - `Cleanuparr-{version}-linux-arm64.zip` for ARM64 systems  
2. Extract the zip file:
   ```bash
   unzip Cleanuparr-{version}-linux-amd64.zip
   cd Cleanuparr-{version}-linux-amd64/
   ```
3. Make the binary executable:
   ```bash
   chmod +x Cleanuparr
   ```
4. Run Cleanuparr:
   ```bash
   ./Cleanuparr
   ```
5. Access the web interface at `http://localhost:11011`

<Note>
To change the port or base path, see [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker).
</Note>

### Running as a Service (Systemd)

To run Cleanuparr as a systemd service:

1. Create a service file:
   ```bash
   sudo nano /etc/systemd/system/cleanuparr.service
   ```

2. Add the following content:
   ```ini
   [Unit]
   Description=Cleanuparr
   After=network.target

   [Service]
   Type=simple
   User=cleanuparr
   Group=cleanuparr
   ExecStart=/opt/cleanuparr/Cleanuparr
   WorkingDirectory=/opt/cleanuparr
   Restart=always
   RestartSec=5
   Environment=PORT=11011
   Environment=BIND_ADDRESS=0.0.0.0
   Environment=BASE_PATH=

   [Install]
   WantedBy=multi-user.target
   ```

3. Create a dedicated user:
   ```bash
   sudo useradd -r -s /bin/false cleanuparr
   ```

4. Move Cleanuparr to `/opt/cleanuparr` and set ownership:
   ```bash
   sudo mkdir -p /opt/cleanuparr
   sudo cp Cleanuparr /opt/cleanuparr/
   sudo chown -R cleanuparr:cleanuparr /opt/cleanuparr
   ```

5. Enable and start the service:
   ```bash
   sudo systemctl enable cleanuparr
   sudo systemctl start cleanuparr
   ```

<Note>
For systemd services, you can also configure PORT and BASE_PATH directly in the service file using the `Environment` directive, or use the [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker) configuration file method.
</Note>

### Arch Linux
[![cleanuparr on AUR](https://img.shields.io/aur/version/cleanuparr?label=cleanuparr)](https://aur.archlinux.org/packages/cleanuparr/)
[![cleanuparr-bin on AUR](https://img.shields.io/aur/version/cleanuparr-bin?label=cleanuparr-bin)](https://aur.archlinux.org/packages/cleanuparr-bin/)

Cleanuparr is available on the [AUR](https://wiki.archlinux.org/index.php/Arch_User_Repository):
- [cleanuparr](https://aur.archlinux.org/packages/cleanuparr/) (source release package)
- [cleanuparr-bin](https://aur.archlinux.org/packages/cleanuparr-bin/) (binary package)

You can install it using your [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) of choice.

Example:
```console
$ yay -Sy cleanuparr
```

<Note>
To change the port or base path for AUR installations, see [Port and Base Path (Non-Docker)](#port-and-base-path-non-docker).
</Note>

</div>

<div className={styles.section}>

<SectionTitle>Port and Base Path (Non-Docker)</SectionTitle>

For all non-Docker installations (Windows, macOS, Linux portable), you can configure the PORT, BIND_ADDRESS and BASE_PATH by creating a configuration file.

### Initial Setup

1. **Start Cleanuparr** for the first time to initialize the application and create the `config` directory
2. Navigate to the `config` directory:
   - **Windows Installer**: `C:\ProgramFiles\Cleanuparr\config\`
   - **Windows Portable**: `[installation-directory]\config\`
   - **macOS Installer**: `/Applications/Cleanuparr.app/Contents/MacOS/config/`
   - **macOS Portable**: `[installation-directory]/config/`
   - **Linux**: `[installation-directory]/config/`

3. **Create** a file named `cleanuparr.json` in the `config` directory with the following contents (modify as needed):

```json
{
  "PORT": 11011,
  "BIND_ADDRESS": "0.0.0.0",
  "BASE_PATH": ""
}
```

4. **Restart Cleanuparr** for the changes to take effect

### Example Configurations

**Running on port 8080:**
```json
{
  "PORT": 8080
}
```
Access via: `http://localhost:8080`

**Binding to localhost only:**
```json
{
  "BIND_ADDRESS": "127.0.0.1"
}
```
Only accessible from the local machine.

**Running with reverse proxy at `/cleanuparr`:**
```json
{
  "BASE_PATH": "/cleanuparr"
}
```
Access via: `http://yourdomain.com/cleanuparr`

**Custom port with base path:**
```json
{
  "PORT": 8080,
  "BASE_PATH": "/apps/cleanup"
}
```
Access via: `http://yourdomain.com:8080/apps/cleanup`

</div>

<div className={styles.section}>

<SectionTitle>Post Installation</SectionTitle>

#### Default Configuration
- **Web Interface**: `http://localhost:[PORT][BASE_PATH]` (default: `http://localhost:11011`)
- Configure your download clients and *arr applications
- Refer to the [Configuration](/docs/category/configuration) section for detailed setup instructions

#### Health Checks
Cleanuparr provides health check endpoints for monitoring and container orchestration. For detailed information about available endpoints and configuration, see the [Health Checks documentation](../configuration/health-checks/).

</div>

</div>
