Knowledge Base: Self-Hosting Invidious with Docker Compose

Invidious is an open-source alternative front-end to YouTube that is privacy-focused. It allows users to watch videos without being tracked by Google, requires no JavaScript to function, and provides a lightweight interface.

This entry covers a hardened Docker Compose deployment featuring the Invidious core, a PostgreSQL database, and the Invidious Companion for enhanced video playback.

2. Infrastructure Architecture

The setup relies on three interconnected containers operating within a private Docker network.

• Invidious (Web): The user interface and API.
• Invidious Companion: A sidecar service that assists with YouTube's more complex video streaming protocols.
• PostgreSQL: The persistent storage for user preferences and internal data.

3. Configuration Requirements (The docker-compose.yml)

When deploying, special attention must be paid to secret lengths and service dependencies to prevent "Hostname lookup failed" errors.

Security Constants

• HMAC Key: A long, random string for signing tokens.
• Companion Key: MUST be exactly 16 characters long and match between the invidious and companion services.
• Database Credentials: Use long, unique alphanumeric strings for POSTGRES_USER and POSTGRES_PASSWORD.

Port Mapping

In this configuration, we map the internal container port 3000 to a custom host port (e.g., 10358) to avoid conflicts with other services on the VPS.

4. Implementation Code

services:
  invidious:
    image: quay.io/invidious/invidious:latest
    restart: unless-stopped
    ports:
      - "10358:3000"
    environment:
      INVIDIOUS_CONFIG: |
        db:
          dbname: invidious
          user: [YOUR_DB_USER]
          password: [YOUR_DB_PASSWORD]
          host: invidious-db
          port: 5432
        check_tables: true
        invidious_companion:
          - private_url: "http://companion:8282/companion"
        invidious_companion_key: "[16_CHAR_SECRET]"
        domain: invidious.nulu.my
        https_only: true
        hmac_key: "[LONG_RANDOM_SECRET]"
    healthcheck:
      test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/stats || exit 1
      interval: 30s
      timeout: 5s
      retries: 2
    depends_on:
      - invidious-db
      - companion

  companion:
    image: quay.io/invidious/invidious-companion:latest
    environment:
       - SERVER_SECRET_KEY=[MATCHING_16_CHAR_SECRET]
    restart: unless-stopped
    cap_drop:
      - ALL
    read_only: false
    volumes:
      - companioncache:/var/tmp/youtubei.js:rw
    security_opt:
      - no-new-privileges:true

  invidious-db:
    image: docker.io/library/postgres:14
    restart: unless-stopped
    volumes:
      - postgresdata:/var/lib/postgresql/data
      - ./config/sql:/config/sql
      - ./docker/init-invidious-db.sh:/docker-entrypoint-initdb.d/init-invidious-db.sh
    environment:
      POSTGRES_DB: invidious
      POSTGRES_USER: [YOUR_DB_USER]
      POSTGRES_PASSWORD: [YOUR_DB_PASSWORD]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]

volumes:
  postgresdata:
  companioncache:

5. Maintenance Commands

6. Common Troubleshooting

"Hostname lookup for companion failed"

Cause: The Invidious service attempted to connect to the Companion service before the latter was fully initialised, or the Companion service crashed. Solution: Ensure depends_on includes companion and that read_only is set to false in the companion service to allow necessary cache writes.

"Secret key must be exactly 16 characters"

Cause: The Companion service has a strict validation rule for the SERVER_SECRET_KEY. Solution: Truncate or regenerate your key to be exactly 16 characters.

Summary: This setup provides a robust, private YouTube experience. By managing the deployment via Docker Compose, we ensure that the environment is reproducible and isolated from the host OS.