This page covers getting Nudgarr running for the first time using Docker Compose, and the environment variables that control its runtime behaviour.

• Docker and Docker Compose installed
• At least one running Radarr or Sonarr instance
• An API key for each instance you want Nudgarr to manage

Copy .env.example from the repo and fill in your values:

PUID=1000
PGID=1000
PORT=8085
CONFIG_PATH=/your/path/to/appdata/nudgarr
# TZ=Europe/London # optional — set to make cron schedule fire in local time
# SECRET_KEY=your-secret-key # optional — auto-generated if not set

version: "3.8"
services:
 nudgarr:
 image: mmagtech/nudgarr:latest
 container_name: nudgarr
 restart: unless-stopped
 ports:
 - "${PORT:-8085}:${PORT:-8085}"
 volumes:
 - ${CONFIG_PATH:-./config}:/config
 environment:
 - PUID=${PUID:-1000}
 - PGID=${PGID:-1000}
 - PORT=${PORT:-8085}
 - CONFIG_FILE=/config/nudgarr-config.json
 - DB_FILE=/config/nudgarr.db
 # - TZ=${TZ:-UTC} # optional — set in .env to make cron fire in local time
 # - SECRET_KEY=${SECRET_KEY}
 read_only: true
 tmpfs:
 - /tmp:rw,noexec,nosuid,nodev,size=64m
 security_opt:
 - no-new-privileges:true
 cap_drop:
 - ALL
 cap_add:
 - CHOWN
 - SETUID
 - SETGID
 pids_limit: 50
 mem_limit: 128m
 cpus: 0.5
 logging:
 driver: json-file
 options:
 max-size: "10m"
 max-file: "3"

docker compose up -d

Navigate to http://<your-host>:8085. On first run, Nudgarr will walk you through the onboarding flow to add your first instance and configure basic settings.

Nudgarr drops privileges and runs as the user you specify so that files written to /config are owned correctly.

Both files are created automatically on first start if they do not exist.

Pull the new image and recreate the container:

docker compose pull
docker compose up -d

No config changes required. No data migration needed. Pull the new image and restart.

The frontend has been completely rewritten to Alpine.js. The horizontal tab bar is replaced by a sidebar with Monitor, Configure, and System groups. History, Imports, CF Score, and Exclusions are consolidated into a single Library panel with a view switcher. New config keys (per-app CF Score toggles) are automatically written with safe defaults on first load.

A hard refresh (Ctrl+Shift+R / Cmd+Shift+R) after upgrading is recommended to ensure fresh assets are loaded.

No config changes required. No data migration needed. Pull the new image and restart. New config keys are automatically written with safe defaults on first load.

No config changes required for most settings. New config keys introduced in v4.2.0 are automatically written with safe defaults on first load:

• radarr_cutoff_enabled and sonarr_cutoff_enabled default to True — existing installs are unaffected
• Migration note: If you previously set radarr_max_movies_per_run or sonarr_max_episodes_per_run to 0 as a way to disable Cutoff Unmet searches, Nudgarr will detect this on upgrade, set the corresponding enabled toggle to False, and reset the max to 1. Your intent is preserved — Cutoff Unmet will be off for that app after the upgrade.

A hard refresh (Ctrl+Shift+R / Cmd+Shift+R) after upgrading is recommended to ensure fresh JS and CSS are loaded.

No config changes required. No data migration needed. Pull the new image and restart. Static assets now include version query strings — browsers will automatically receive fresh JS and CSS without a hard refresh.

No config changes required. No data migration needed. Pull the new image and restart. A one-time hard refresh may be needed after the upgrade to clear cached static files.

Upgrade to v3.2.0 first, then to v4.0.0. The SQLite migration that moves data from legacy JSON files ran in v3.1.0 and v3.2.0. v4.0.0 assumes all installs are already on the current schema — direct upgrades from pre-v3.2.0 installs are not supported and data will not be migrated automatically.

After first run, add or edit Radarr and Sonarr instances from the Instances tab in the UI:

1. Click + Add Instance (or the edit icon on an existing one)
2. Choose the app type — Radarr or Sonarr
3. Enter a display name, the base URL (e.g. http://192.168.1.10:7878), and your API key
4. Save — Nudgarr will immediately test the connection and display a health indicator

Each instance can be independently enabled or disabled without removing it.

Nudgarr is designed for local network use. The login screen provides basic access control — it is not a hardened authentication layer. Passwords are stored as PBKDF2-HMAC-SHA256 hashes with a unique random salt. Failed login attempts trigger a progressive lockout.

Recommendations:

• Run on your LAN only
• For remote access, use a VPN (Tailscale, WireGuard) or a reverse proxy with HTTPS
• Do not expose port 8085 directly to the internet