Setup & Configuration

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

Prerequisites

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

Quick start

1. Create your `.env` file

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

2. Create your `docker-compose.yml`

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"

3. Start the container

docker compose up -d

4. Open the UI

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.

Environment variables

Variable	Default	Description
`PUID`	`1000`	User ID the container runs as
`PGID`	`1000`	Group ID the container runs as
`PORT`	`8085`	Port the web UI listens on
`CONFIG_FILE`	`/config/nudgarr-config.json`	Path to the JSON config file
`DB_FILE`	`/config/nudgarr.db`	Path to the SQLite database
`SECRET_KEY`	(auto-generated)	Flask session secret. Set explicitly if you want sessions to survive container restarts
`TZ`	(system default)	Timezone for cron evaluation — e.g. `Europe/London`, `America/New_York`

PUID / PGID

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

Platform	Typical values
Linux	`PUID=1000` `PGID=1000`
Unraid	`PUID=99` `PGID=100` (nobody:users)
Synology	Match your DSM user — check with `id` over SSH

Data files

File	Purpose
`/config/nudgarr-config.json`	All application settings
`/config/nudgarr.db`	SQLite database — history, stats, exclusions, and app state
`/config/logs/nudgarr.log`	Rotating log file — 5 MB per file, 3 backups, 20 MB total cap
`/config/nudgarr-secret.key`	Persisted session secret — auto-created on first start

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

Upgrading

Pull the new image and recreate the container:

docker compose pull
docker compose up -d

Upgrading to v4.2.0

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.

Upgrading to v4.1.0

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.

Upgrading to v4.0.0

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.

Upgrading from v3.1.x or earlier

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.

Adding instances

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

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

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

Security

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

Prerequisites​

Quick start​

1. Create your .env file​

2. Create your docker-compose.yml​

3. Start the container​

4. Open the UI​

Environment variables​

PUID / PGID​

Data files​

Upgrading​

Upgrading to v4.2.0​

Upgrading to v4.1.0​

Upgrading to v4.0.0​

Upgrading from v3.1.x or earlier​

Adding instances​

Security​