How to Deploy Radarr with Docker Compose: Smart Movie Collection Management

Radarr is a leading open-source (GPL-3.0) Smart PVR (Personal Video Recorder) and movie collection management platform designed for Usenet and BitTorrent users. Forked originally from Sonarr, Radarr is purpose-built to automate the complete lifecycle of movie curation: discovering upcoming theatrical and digital releases, monitoring indexer RSS feeds, sending grab requests to download clients, importing and organizing completed files into structured folders, and continuously upgrading media files when higher-quality releases become available.

Instead of manually browsing torrent trackers, searching NZB indexers, and renaming cluttered release filenames, Radarr operates autonomously as a continuous background daemon. It communicates with external metadata providers such as The Movie Database (TMDB) and IMDb to maintain comprehensive metadata, posters, backdrops, and release date schedules across theatrical, digital, and physical distribution windows.

Radarr's architecture centers around several core automation components:

• Indexer Integration: Automatically queries Usenet indexers (via Newznab protocols) and BitTorrent trackers (via Torznab, Prowlarr, or Jackett) using scheduled RSS sync and targeted interactive searches with detailed release rejection reasons.
• Download Client Orchestration: Seamlessly interfaces with Usenet downloaders (including SABnzbd and NZBGet) and BitTorrent clients (such as qBittorrent, Transmission, Deluge, rTorrent, and uTorrent), managing download categories, priorities, and real-time progress.
• Intelligent Post-Processing & Standardized Renaming: Identifies finished downloads, parses scene release naming patterns (codecs, audio channels, source tags), hardlinks or moves video files into standardized movie directories (such as Title (Year)/Title (Year) [Quality].mkv), extracts archives, and purges unwanted sample files.
• Quality Profiles & Custom Formats: Empowers administrators to build detailed quality target ladders (SD, HD-720p, HD-1080p, Ultra-HD 4K, Bluray Remux) combined with score-based Custom Formats (for HDR10, Dolby Vision, audio codecs like TrueHD/Atmos, or preferred release groups). When a higher-scoring release surfaces, Radarr automatically fetches the upgrade.
• Media Server & Notification Webhooks: Automatically alerts downstream media servers like Plex, Jellyfin, Emby, and Kodi to refresh their libraries upon successful import, while broadcasting event notifications to Discord, Telegram, Pushbullet, or custom webhooks.
• Modern Web Application & API: Provides a responsive React 18 Single Page Application (SPA) with SignalR real-time websocket updates, backed by an ASP.NET Core service exposing full REST APIs (v3) backed by an embedded SQLite database.

This guide walks through deploying Radarr v6 (6.4.4.10685) using Docker Compose with the official LinuxServer image, completing the first-run browser authentication setup, mounting persistent media volumes, and tracking your first movie.

Prerequisites

Before deploying Radarr, ensure your host environment meets the following requirements:

• Docker Engine & Docker Compose: Docker Engine 20.10+ and Docker Compose v2+ installed and active on your host (docker compose version).
• User Permissions (UID/GID): Determine the user and group ID of the account managing your media files (typically 1000:1000 via id -u and id -g) so file permissions remain consistent across Docker mounts.
• Network Port: An available host port for Radarr's Web UI and REST API. Radarr listens internally on port 7878. In this guide, host port 3000 (or 7878) is mapped to container port 7878.
• Storage Volumes: Sufficient disk space on local or networked storage for three directories:

- Configuration directory (/config) for database files (radarr.db, logs.db) and runtime configuration (config.xml). - Movie library directory (/movies) for organized film directories and video files. - Download directory (/downloads) where your torrent or Usenet client places completed downloads.

• Modern Web Browser: Chrome, Firefox, Safari, or Edge to access the web interface.

Exact Install Steps

Follow these steps to deploy Radarr using Docker Compose with persistent bind mounts.

1. Create Deployment Directory Structure

Create a dedicated directory for your deployment manifests and mount directories:

mkdir -p radarr-deploy/config radarr-deploy/movies radarr-deploy/downloads
cd radarr-deploy

• config/: Contains Radarr's SQLite database, logs, and config.xml.
• movies/: Root destination for your organized movie library.
• downloads/: Ingest destination for completed files from your download client.

2. Configure Environment Variables (.env)

Create a .env file to define the project name, port binding, and file ownership:

cat > .env <<'EOF'
COMPOSE_PROJECT_NAME=shortform-radarr
IMAGE=lscr.io/linuxserver/radarr:latest
RADARR_PORT=3000
PUID=1000
PGID=1000
TZ=Etc/UTC
EOF

If you prefer Radarr's standard port, change RADARR_PORT=3000 to RADARR_PORT=7878. Ensure PUID and PGID match your host user ID (id -u and id -g).

3. Create Docker Compose File (docker-compose.yml)

Create the docker-compose.yml file:

services:
  radarr:
    image: ${IMAGE}
    container_name: ${COMPOSE_PROJECT_NAME}-radarr
    environment:
      - PUID=${PUID}
      - PGID=${PGID}
      - TZ=${TZ}
    ports:
      - "127.0.0.1:${RADARR_PORT}:7878"
    volumes:
      - "./config:/config"
      - "./movies:/movies"
      - "./downloads:/downloads"
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:7878/ping || exit 1"]
      interval: 5s
      timeout: 3s
      retries: 10
      start_period: 10s
    restart: unless-stopped

4. Start the Radarr Container

Launch Radarr in detached mode:

docker compose up -d

Docker Compose pulls the LinuxServer Radarr image, creates the default network, and launches the container with configured storage mounts.

5. Wait for Readiness

Wait until Radarr's internal Kestrel web server initializes and responds to health ping requests:

timeout=120
while [ $timeout -gt 0 ]; do
  if curl -fsS http://localhost:3000/ping >/dev/null 2>&1; then
    echo "Radarr is ready!"
    break
  fi
  sleep 2
  timeout=$((timeout - 2))
done
[ $timeout -gt 0 ] || { echo "Timed out waiting for Radarr"; docker compose logs --tail 50; exit 1; }

Once the loop outputs Radarr is ready!, the service is live and ready for first-run configuration.

Browser Setup

Once the container is healthy, open your web browser and navigate to:

http://localhost:3000/

*(If you configured RADARR_PORT=7878, navigate to http://localhost:7878/).*

Step 1: Complete the First-Run Authentication Setup

Radarr v6 enforces authentication security out of the box. On your first visit, Radarr displays a blocking Authentication Required modal that must be configured before accessing the application dashboard.

Configure the authentication settings:

1. Authentication Method: Select Forms (Login Page).
2. Authentication Required: Select Disabled for Local Addresses. This enables password-free local access while safeguarding remote access.
3. Username: Enter an administrative username (e.g., demo).
4. Password: Enter a secure password (e.g., demo1234).
5. Allowed Hosts: Enter localhost (or your domain/IP). Important: Radarr strictly requires this field when *Authentication Required* is set to *Disabled for Local Addresses*; leaving it empty causes an HTTP 400 validation error.

Click Save. The modal dismisses and Radarr mounts the main movie library interface.

Step 2: Add a Media Root Folder

Before adding movies, Radarr requires a designated root storage directory where film folders will be organized.

1. Navigate to Settings in the left sidebar menu.
2. Click the Media Management tab.
3. Scroll down to the Root Folders section.
4. Click Add Root Folder.

1. In the file path modal, select or enter /movies, then click the blue checkmark button.
2. The path /movies immediately appears in the Root Folders list, showing accessible free storage space (approximately 406 GiB). Root folders save automatically upon addition without needing an extra page save.

Step 3: Search for and Add a Movie

With media storage mounted, you can add your first film to track.

1. Click Movies › Add New in the sidebar (or use the top search input).
2. Type a title, such as Inception.
3. Radarr queries The Movie Database (TMDB) metadata service and returns matching movie cards complete with cover artwork, release years, and descriptions.

1. Click the Inception (2010) card to open the Add Movie configuration modal.
2. Set your movie tracking preferences:

- Root Folder: /movies - Monitor: Movie Only - Minimum Availability: Released - Quality Profile: HD-1080p - Leave the "Start search for missing movie" option checked. Since no download clients or indexers are linked yet, Radarr safely creates the library tracking record without downloading.

1. Click Add Movie. The modal closes and the movie is registered in Radarr's database.

Step 4: Explore the Movie Library & Movie Details

Navigate back to Movies to inspect your updated library:

• Inception appears on the library grid as a poster card showing its Monitored status and HD-1080p quality profile badge.
• A red bar beneath the poster indicates that the title is monitored but the file has not yet been acquired.
• The footer summary reflects Movies: 1, Movie Files: 0, Monitored: 1.

Click the poster card to view the detailed movie view at /movie/27205 (Radarr references TMDB IDs for film routes):

• View high-resolution backdrop fanart, movie overview, studio information, and file status.
• Inspect the complete Cast & Crew listing (featuring Leonardo DiCaprio, Joseph Gordon-Levitt, Ken Watanabe, Tom Hardy, Elliot Page, Dileep Rao, and director Christopher Nolan).

Step 5: Review Calendar & Quality Profiles

Explore Radarr's scheduling and quality management features:

• Calendar: Click Calendar in the sidebar. Radarr's calendar visualizes upcoming theatrical, digital, and disc release dates for tracked titles. Note that previously released catalog films (like *Inception*, released in 2010) will not show entries in the current month's view, as their distribution windows have passed.

• Quality Profiles: Navigate to Settings › Profiles to view the standard quality tiers (Any, Ultra-HD, HD-1080p, HD-720p, SD).
• Click on HD-1080p to inspect the quality hierarchy ladder. You can drag and drop quality tiers (WEB 1080p, Bluray 1080p, HDTV 1080p), group equivalent qualities, and configure the upgrade cutoff threshold.

Verification

To verify that your Radarr deployment is healthy and operational, perform the following verification checks:

1. HTTP Liveness Ping

Check Radarr's liveness endpoint:

curl -fsS http://localhost:3000/ping

Expected output:

{"status":"OK"}

2. Frontend Initialization API

Verify that Radarr's bootstrap configuration endpoint is functioning and provides an API key:

curl -fsS http://localhost:3000/initialize.json | grep -o '"apiKey":"[^"]*"'

Expected output:

"apiKey":"<your-radarr-api-key>"

3. Application Web Shell

Verify that the React SPA HTML shell loads correctly:

curl -fsS http://localhost:3000/ | grep -q "<title>Radarr</title>" && echo "Web UI OK"

Expected output:

Web UI OK

4. Container Health Check

Inspect Docker's internal health status:

docker compose ps

The container status should display Up (healthy).

5. System Status Dashboard

Navigate to System › Status (http://localhost:3000/system/status) in your browser to inspect runtime metrics:

• Version: 6.4.4.10685 (packaged by LinuxServer 6.4.4.10685-ls324)
• Runtime: .NET 8.0.27 running inside Alpine Linux
• Docker: Yes
• Database: SQLite 3.53.4
• AppData Directory: /config
• Disk Space: Verified storage paths for /config, /movies, and /downloads

A red badge with number 3 on the System tab is expected on a new installation; it indicates that no indexers or download clients have been connected yet.

Troubleshooting

Symptom / Error	Root Cause	Resolution
HTTP 400 Bad Request saving first-run auth modal: "Allowed Hosts is required..."	When *Authentication Required* is set to *Disabled for Local Addresses*, Radarr requires explicit allowed host headers to prevent DNS rebinding attacks.	In the auth configuration modal, enter localhost (or your domain/IP) into the Allowed Hosts field before clicking Save.
Container exits immediately or crashes with port binding error	Host port 3000 (or 7878) is already bound by another process or container on your system.	Check active ports with ss -ltn '( sport = :3000 or sport = :7878 )'. Update RADARR_PORT in .env to an unused port (e.g., 3002 or 17878) and run docker compose up -d.
Permission denied writing to /config or /movies, or CorruptDatabaseException	The PUID or PGID in .env does not match the ownership of your host mount directories (./config, ./movies, ./downloads).	Run id -u and id -g on the host. Update .env with those values, run chown -R <uid>:<gid> config movies downloads, and restart the container. Avoid mounting /config over NFS/CIFS without POSIX locking support.
Movie search queries return no results or timeout	Radarr cannot establish outbound HTTPS connections to api.radarr.video or api.themoviedb.org.	Check DNS resolution and internet egress inside the container using docker compose exec radarr curl -I https://api.radarr.video. Ensure host firewalls allow container egress.
Calendar displays no movies after adding a title	The added title was released in the past (e.g., *Inception* was released in 2010), so it has no upcoming theatrical, digital, or physical release windows in the current month.	Add an unreleased or upcoming movie to see release dates rendered on the current month's view, or use Agenda view to inspect release milestones.
Red health badge with number 3 on the System tab	Clean installation notifications reminding you that automated downloading requires external download clients and indexers.	Configure indexers under Settings › Indexers (or link Prowlarr) and add a download client (such as qBittorrent or SABnzbd) under Settings › Download Clients.

Teardown / Cleanup

If you need to stop and completely remove the Radarr test deployment, execute the following commands from your deployment directory:

# 1. Stop and remove containers, networks, and internal volumes
docker compose down --remove-orphans -v

# 2. (Optional) Remove the persistent data directories
cd ..
rm -rf radarr-deploy

# 3. Verify no lingering containers remain
docker ps -a --filter "name=shortform-radarr"

Assumptions & Decisions

• First-Run Authentication Requirement: Radarr v6 ships with authentication enforcement enabled (AuthenticationRequired=Enabled). We documented the first-run configuration modal directly in the guide, including the requirement to populate Allowed Hosts with localhost when selecting *Disabled for Local Addresses* to avoid HTTP 400 validation failures.
• Docker Compose Deployment: While the upstream source repository does not bundle a root docker-compose.yml, Radarr is standardly deployed across homelab environments via published OCI container images. We utilized the official LinuxServer image (lscr.io/linuxserver/radarr:latest) with Docker Compose, providing instant zero-compiler reproducibility.
• Port Mapping: We mapped host port 3000 to internal container port 7878 to avoid common port collisions with existing services on host port 7878, while noting that 7878 is Radarr's default port.
• Quality Profile & Movie Selection: In the walkthrough, *Inception (2010)* was tracked with the HD-1080p quality profile, Movie Only monitor mode, and Released minimum availability, demonstrating quality ladder configuration and metadata indexing.
• Detail URL Structure: Radarr v6 uses the TMDB ID in detail routes (/movie/27205) rather than a slug-based URL.
• Calendar Airings Nuance: We explicitly clarified why catalog movies released in prior years do not show events on the current month's calendar view, avoiding user confusion about calendar functionality.
• Shipped Version & Runtime: The deployed LinuxServer image runs Radarr 6.4.4.10685 on .NET 8.0.27 (SQLite 3.53.4) on Alpine Linux, whereas the upstream Git repository's develop branch targets .NET 10. We documented the exact runtime and version metrics reflected by the live deployment.