Setup and Configuration

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
# 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
      # - 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

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 from v3.0.0 or earlier

All history, stats, and exclusions move to the SQLite database in v3.1.0. Existing JSON files (nudgarr-stats.json, nudgarr-state.json, nudgarr-exclusions.json) are migrated automatically on first start. The original files are left in place and can be removed once you're satisfied with the upgrade.

Upgrading from v2.x

No config changes are required. The mobile layout activates automatically on devices under 500px wide. The onboarding flow will not re-run — your existing config is preserved.

---

Adding instances

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.

---

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