Skip to content

Installation

Jump to bottom
o51r15 edited this page Jun 18, 2026 · 1 revision

Pinchfork is distributed as a prebuilt Docker image and requires a PostgreSQL container. A PO Token sidecar is strongly recommended — see SABR Bypass and PO Tokens for why.

Naming note: The app service uses the pinchfork name. The database container, DB user, and DATABASE_URL segments keep the pinchflat name — they are inherited from the upstream-derived image and renaming them breaks the app. These are marked with comments in the compose file below.

Quick start

Step 1 — Create your compose file.

A complete annotated three-container compose file is available in the repo at docker-compose.sample.yml. A minimal version:

services:
  bgutil-provider:                                  # PO Token sidecar (recommended)
    container_name: bgutil-provider
    image: brainicism/bgutil-ytdlp-pot-provider:1.3.1
    restart: unless-stopped

  pinchfork-db:                                     # Postgres (required)
    container_name: pinchfork-db
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: pinchflat                       # inherited — do not rename
      POSTGRES_PASSWORD: your_password_here          # must match DATABASE_URL below
      POSTGRES_DB: pinchflat                         # inherited — do not rename
    volumes:
      - pinchfork_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pinchflat"]
      interval: 10s
      timeout: 5s
      retries: 5

  pinchfork:                                        # the app
    container_name: pinchfork
    image: ghcr.io/o51r15/pinchfork:latest
    restart: unless-stopped
    depends_on:
      pinchfork-db:
        condition: service_healthy
      bgutil-provider:
        condition: service_started
    environment:
      - TZ=America/New_York
      - DATABASE_URL=ecto://pinchflat:your_password_here@pinchfork-db/pinchflat
      - POOL_SIZE=10
    ports:
      - "8945:8945"
    volumes:
      - /path/to/config:/config
      - /path/to/downloads:/downloads

volumes:
  pinchfork_pgdata:

Step 2 — Start it:

docker compose -f /path/to/your/docker-compose.yml up -d

Migrations run automatically at startup. The app will be available at http://your-server:8945.

Updating

docker compose pull && docker compose up -d

This pulls the newest image and recreates the container. Your data (Postgres volume + /config bind mount) is preserved.

Environment variables

Name Required? Default Notes
DATABASE_URL Yes — Postgres connection string: ecto://user:pass@host/db
TZ No UTC Must follow IANA TZ format
POOL_SIZE No 10 Postgres connection pool size
LOG_LEVEL No debug Can be set to info to reduce noise
UMASK No 022 Unraid users may want 000
BASIC_AUTH_USERNAME No — Enables basic auth when both username and password are set
BASIC_AUTH_PASSWORD No — Enables basic auth when both username and password are set
EXPOSE_FEED_ENDPOINTS No false Set to expose RSS/streaming endpoints outside basic auth
ENABLE_IPV6 No false Set to any non-blank value to enable
TZ_DATA_DIR No /etc/elixir_tzdata_data Container path for timezone database
BASE_ROUTE_PATH No / Base path for reverse proxy subdirectory deployments
YT_DLP_WORKER_CONCURRENCY No 2 yt-dlp workers per queue. Set to 1 if getting IP limited
YT_DLP_VERSION No stable yt-dlp update behavior: stable, nightly, master, pinned/none to disable, or a specific version like 2025.12.08
ENABLE_PROMETHEUS No false Set to any non-blank value to enable
LOCALTEMP No — Stage yt-dlp intermediate files on a local disk. Required when /downloads is a network mount. See Local Temp Staging.

Reverse proxies

Pinchfork makes heavy use of websockets for real-time updates. Ensure your reverse proxy is configured to pass websocket connections through. For RSS feed access outside of basic auth, see Podcast RSS Feeds.

File permissions

Ensure the host directories you've mounted (/config, /downloads) are writable by the user running the Docker container. If you encounter permission errors, check the container logs for guidance.

It is not recommended to run the container as root. If you need to run a command as root inside the container, use su — there is no password set for the root user.

Network mount downloads

If your /downloads directory is an SMB, CIFS, or NFS mount, see Local Temp Staging. Running yt-dlp's intermediate work directly on a network mount can cause corrupted files; the LOCALTEMP option stages everything locally and moves only the finished file across.

Clone this wiki locally