Skip to content

Installation

Jump to bottom
TheBadFella edited this page Sep 20, 2026 · 3 revisions

Installation

Pinchflat-ngx publishes Linux images for amd64 and arm64 at ghcr.io/thebadfella/pinchflat-ngx. Docker selects the correct architecture automatically.

Before you begin

Install Docker Engine with Docker Compose and create two writable host directories:

  • config stores the SQLite database (SQLite image), logs, metadata, cookies, application state, and in-app PostgreSQL dumps when that image is used.
  • downloads stores downloaded media.

Keep config on a local disk when possible. SQLite's default WAL journal mode is not designed for most network file systems.

The latest image uses SQLite. A separate latest-postgres image uses PostgreSQL. Pick one image; the adapter is built into the image and is not a runtime switch on the SQLite tag.

Docker Compose

Create a directory for Pinchflat-ngx and save this as compose.yaml:

services:
  pinchflat-ngx:
    image: ghcr.io/thebadfella/pinchflat-ngx:latest
    container_name: pinchflat-ngx
    environment:
      TZ: America/Regina
    ports:
      - "8945:8945"
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    restart: unless-stopped

Replace America/Regina with an IANA timezone name, then start Pinchflat-ngx:

docker compose up -d
docker compose ps

Open http://localhost:8945. The first startup may take a short time to report healthy.

PostgreSQL image

To start a new installation on PostgreSQL, use ghcr.io/thebadfella/pinchflat-ngx:latest-postgres and set DATABASE_ADAPTER plus DATABASE_URL. Current images expect PostgreSQL 18:

services:
  pinchflat-ngx:
    image: ghcr.io/thebadfella/pinchflat-ngx:latest-postgres
    container_name: pinchflat-ngx
    environment:
      DATABASE_ADAPTER: postgres
      DATABASE_URL: ecto://pinchflat-ngx:change-me@postgres/pinchflat-ngx
      TZ: America/Regina
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "8945:8945"
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    restart: unless-stopped

  postgres:
    image: postgres:18-alpine
    environment:
      POSTGRES_DB: pinchflat-ngx
      POSTGRES_PASSWORD: change-me
      POSTGRES_USER: pinchflat-ngx
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pinchflat-ngx -d pinchflat-ngx"]
      interval: 5s
      timeout: 5s
      retries: 10
    volumes:
      - postgres-data:/var/lib/postgresql
    restart: unless-stopped

volumes:
  postgres-data:

The PostgreSQL image creates and migrates its own schema. It does not copy an existing SQLite database. PostgreSQL 16 or earlier volumes are not compatible with PostgreSQL 18 as-is; dump and restore, or follow an explicit major-version upgrade, before reusing that data.

Keep using latest for an existing SQLite installation until you have migrated its data separately. In-app PostgreSQL dumps are documented in Backups and Restore.

Optional PO-token provider

Leave this unset unless YouTube presents SABR or authentication problems. Add a bgutil-compatible provider on the Compose network and set POT_PROVIDER_URL to its internal URL, for example http://pot-provider:4416. Do not publish the provider's port. Start it with the compose profile you assign to that service.

Pinchflat-ngx images include the matching bgutil yt-dlp plugin. Settings > Diagnostics reports a bounded /ping health check and never displays tokens. See Environment Variables and yt-dlp's PO-token guide.

Optional local download staging

Set DOWNLOAD_STAGING_PATH to an absolute path inside the container when downloads should finish on local disk before their completed files are transferred to /downloads. Unset keeps the existing direct-to-library behavior.

Mount a local directory at that path. Staging and /downloads may be on different filesystems. The path must be writable and different from the media root. See Environment Variables.

Pin a release

latest follows the newest published release. For a controlled deployment, replace it with a tag from the releases page. A pinned tag makes upgrades and rollbacks predictable.

File permissions

Both mounted directories must be writable by the user that runs the container. Do not run the container as root solely to bypass a permissions error; files created as root can become inaccessible to media servers and backup jobs.

The image uses a default UMASK of 022. Override it only when your storage layout requires different permissions.

Secure the web interface

An unconfigured installation does not require a login. Before publishing Pinchflat-ngx through a reverse proxy, configure either:

The reverse proxy must support WebSocket connections for live interface updates. Use HTTPS whenever credentials or session cookies cross an untrusted network.

See Environment variables for the remaining deployment controls.

Pinchflat-ngx

Clone this wiki locally