Docker

Docker

🌐 English · Deutsch

Official image: ghcr.io/pd-codes/mediaforge:latest (Debian-based, includes FFmpeg, mpv, Xvfb and Patchright Chromium for captchas).

Warning

NAS devices (UGREEN, Synology): Both are supported, but MediaForge's code is not optimized for these two NAS platforms and will not be — so expect recurring issues (Docker permissions, storage/DSM quirks, the captcha browser). We're happy to help with installation, but we do not optimize MediaForge for UGREEN or Synology. For the smoothest experience, use a standard Linux, Windows or macOS Docker host.

docker-compose (recommended)

services:
  mediaforge:
    container_name: mediaforge
    image: ghcr.io/pd-codes/mediaforge:latest
    ports:
      - "8080:8080"
    volumes:
      - ./Downloads:/app/Downloads          # downloads on the host
      - mediaforge-data:/home/mediaforge/.mediaforge  # configuration & database
    # security hardening
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp:mode=1777,size=512m
      - /run:size=64m
    restart: unless-stopped

volumes:
  mediaforge-data:

Important: Create ./Downloads before the first start (mkdir -p Downloads) — otherwise Docker creates the folder as root and you get permission errors (the container runs as the unprivileged user mediaforge).

First-time setup

On first start the setup token appears in the container log:

docker compose logs -f mediaforge
# → open http://<HostIP>:8080/setup?token=<token>

Alternatively, create the admin account directly via environment variables (skips the setup page):

    environment:
      MEDIAFORGE_WEB_ADMIN_USER: "admin"
      MEDIAFORGE_WEB_ADMIN_PASS: "changeme"

Optional environment variables

All settings are configurable via the WebUI and stored in the database (volume mediaforge-data). Env variables are only useful for initial configuration/automation:

    environment:
      # SSO / OIDC (see Authentication)
      MEDIAFORGE_WEB_SSO: "1"
      MEDIAFORGE_WEB_FORCE_SSO: "1"
      MEDIAFORGE_OIDC_ISSUER_URL: "https://keycloak.example.com/realms/myrealm"
      MEDIAFORGE_OIDC_CLIENT_ID: "mediaforge"
      MEDIAFORGE_OIDC_CLIENT_SECRET: "secret"
      # reverse proxy
      MEDIAFORGE_WEB_BASE_URL: "https://mediaforge.example.com"

Technical details

• The container runs mediaforge -wP 8080 -wN -wH 0.0.0.0 behind an Xvfb display (:99) — required so the captcha browser has a "real" display even headless.
• Timezone/locale default to Europe/Berlin / de_DE.UTF-8 (overridable via TZ/LANG) — realistic values improve the captcha success rate.
• Built-in healthcheck: verifies every 30 s that the WebUI responds.
• Download path inside the container: /app/Downloads (preset via MEDIAFORGE_DOWNLOAD_PATH).

Reverse proxy (nginx, Traefik, …)

1. Set MEDIAFORGE_WEB_BASE_URL to the public https:// URL (or in the UI under Settings) — this generates correct absolute URLs and enables secure cookies.
2. Register https://<domain>/oidc/callback as the redirect URI at your OIDC provider.
3. No WebSocket support needed; plain HTTP proxying is sufficient.

Updating

docker compose pull
docker compose up -d

Configuration and queue survive thanks to the mediaforge-data volume.