Invidious Companion

https://docs.invidious.io/companion-installation
Admin
Invidious Companion is a supplementary service for Invidious, an open-source YouTube front-end. It...
Tokens:32,785
Snippets:222
Trust Score:9.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Temporary PostgreSQL Container for Invidious Database Initialization

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Launches a temporary PostgreSQL container to facilitate initial database setup and migration for Invidious. It maps the previously created volume and sets up necessary environment variables.

```bash
podman run --rm -it --name invidious-init -v invidious-db:/var/lib/postgresql/data:Z -p 5432:5432 -e POSTGRES_DB=invidious -e POSTGRES_USER=kemal -e POSTGRES_PASSWORD=kemal docker.io/library/postgres:14
```

--------------------------------

### Build and Configure Invidious Application

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Compiles the Invidious application using `make` and then sets up the configuration file by copying the example and instructing the user to edit it, specifically to include the previously generated `po_token` and `visitor_data`.

```Shell
make

# Configure config/config.yml as you like
cp config/config.example.yml config/config.yml

# edit config.yaml to include po_token and visitor_data previously generated

edit config/config.yaml
```

--------------------------------

### Start Invidious Application Pod via Systemd

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Initiates the entire Invidious application pod, including all its associated containers, using the systemd user service.

```bash
systemctl --user start invidious-pod
```

--------------------------------

### Start Podman Pod via Systemd

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Reloads the systemd daemon and enables/starts the 'pod-videos.service' user service, which manages the entire 'videos' Podman pod and its containers.

```bash
systemctl --user daemon-reload
systemctl --user enable --now pod-videos.service
```

--------------------------------

### Create Podman Systemd Container Unit for Invidious Application

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Defines the main Invidious application container as a systemd unit, linking it to the environment file and ensuring it starts after the database service.

```bash
cat > ~/.config/containers/systemd/invidious.container <<EOF
[Container]
ContainerName=invidious
EnvironmentFile=%h/.config/containers/systemd/invidious.env
Image=quay.io/invidious/invidious:latest
Pod=invidious.pod
[Unit]
After=invidious-db.service
EOF
```

--------------------------------

### Start Invidious Application

Source: https://docs.invidious.io/companion-installation/installation

Command to start the Invidious application directly from its executable.

```Shell
./invidious
```

--------------------------------

### Configure PostgreSQL Database for Invidious

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Starts the PostgreSQL service, creates a new database user 'kemal' with a specified password, creates the 'invidious' database owned by 'kemal', and imports necessary SQL schemas for channels, videos, users, and playlists.

```Shell
brew services start postgresql
createdb
psql -c "CREATE ROLE kemal WITH LOGIN PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml
createdb -O kemal invidious
psql invidious kemal < config/sql/channels.sql
psql invidious kemal < config/sql/videos.sql
psql invidious kemal < config/sql/channel_videos.sql
psql invidious kemal < config/sql/users.sql
psql invidious kemal < config/sql/session_ids.sql
psql invidious kemal < config/sql/nonces.sql
psql invidious kemal < config/sql/annotations.sql
psql invidious kemal < config/sql/playlists.sql
psql invidious kemal < config/sql/playlist_videos.sql
```

--------------------------------

### Create Invidious Database Volume with Podman

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Initializes a new Podman volume specifically for the Invidious PostgreSQL database, ensuring data persistence.

```bash
podman volume create invidious-db
```

--------------------------------

### Invidious Development Setup with Docker Compose

Source: https://docs.invidious.io/companion-installation/installation

These commands clone the Invidious repository, navigate into it, and then build and start the Invidious services using Docker Compose. This method is intended for development purposes as it builds the Docker image directly from the source code, allowing for easier iteration and testing of changes.

```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
docker-compose up
```

--------------------------------

### Clone Invidious Repository

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Clones the Invidious source code repository into the specified path. This repository contains necessary configuration files and scripts for database initialization.

```bash
cd <INV-PATH>
git clone https://github.com/iv-org/invidious.git
```

--------------------------------

### Docker Compose Development Setup Commands

Source: https://docs.invidious.io/companion-installation/companion-installation

Provides commands for a simplified Docker Compose setup for development, which clones the Invidious repository and starts the services, building images from source. This method is suitable for local development and testing.

```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
docker-compose up
```

--------------------------------

### Create Podman Container for Invidious

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Creates a Podman container for the Invidious application, linking it to the 'videos' pod. It sets up health checks and mounts the Invidious configuration file.

```bash
podman create --rm \
--pod videos \
--name invidious \
--label "io.containers.autoupdate=registry" \
--health-cmd="wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1" \
--health-interval=30s \
--health-timeout=5s \
--health-retries=2 \
-v <INV-PATH>/config.yml:/invidious/config/config.yml:z,U \
quay.io/invidious/invidious:latest
```

--------------------------------

### Build and Configure Invidious Application

Source: https://docs.invidious.io/companion-installation/installation

Switches to the Invidious user, navigates to the application directory, compiles the source code, copies the example configuration file, and prompts for manual editing to include `po_token` and `visitor_data` before running database migrations.

```bash
su - invidious
cd invidious
make

# Configure config/config.yml as you like
cp config/config.example.yml config/config.yml

# edit config.yaml to include po_token and visitor_data previously generated

edit config/config.yaml

# Deploy the database
./invidious --migrate

exit
```

--------------------------------

### Install Invidious System Dependencies

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Installs required system libraries and tools for Invidious using Homebrew, including Crystal, PostgreSQL, ImageMagick, and librsvg.

```Shell
brew update
brew install crystal postgresql imagemagick librsvg
```

--------------------------------

### Clone Invidious Repository for Production Setup

Source: https://docs.invidious.io/companion-installation/installation

These commands clone the Invidious source code repository from GitHub and navigate into the newly created `invidious` directory. This step is necessary for the production Docker Compose setup to access the `init-invidious-db.sh` file and the `config/sql` directory for mounting to the PostgreSQL container.

```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
```

--------------------------------

### Create Podman Systemd Container Unit for Invidious Signature Helper

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Sets up a systemd unit file for the Invidious signature helper container, which is essential for handling YouTube signatures.

```bash
cat > ~/.config/containers/systemd/invidious-sig-helper.container <<EOF
[Container]
ContainerName=invidious-sig-helper
Environment=RUST_LOG=info
Image=quay.io/invidious/inv-sig-helper:latest
Exec=--tcp 0.0.0.0:12999
Pod=invidious.pod
EOF
```

--------------------------------

### Start Invidious Production Services with Docker Compose

Source: https://docs.invidious.io/companion-installation/installation

This command starts the Invidious services defined in the `docker-compose.yml` file in detached mode (`-d`), allowing the services to run in the background. It brings up the Invidious application, signature helper, and PostgreSQL database, making the Invidious instance accessible according to the configured ports.

```bash
docker compose up -d
```

--------------------------------

### Install Podman on RHEL-based Systems

Source: https://docs.invidious.io/companion-installation/community-installation-guide

This command installs Podman and its necessary packages on RHEL-based and RHEL-like systems using the dnf package manager, typically found in Fedora, CentOS, and RHEL distributions.

```bash
sudo dnf install podman
```

--------------------------------

### Build and Configure Invidious on MacOS

Source: https://docs.invidious.io/companion-installation/companion-installation

Builds the Invidious application using 'make' and then copies the example configuration file to `config/config.yml` for customization.

```bash
make

# Configure config/config.yml as you like
cp config/config.example.yml config/config.yml
```

--------------------------------

### Create Podman Systemd Volume Unit for Invidious Database

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Generates a systemd unit file (.volume) for the Invidious database volume, allowing systemd to manage its lifecycle.

```bash
cat > ~/.config/containers/systemd/invidious-db.volume <<EOF
[Volume]
VolumeName=invidious-db
EOF
```

--------------------------------

### Migrate Invidious Database Schema

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Executes SQL migration scripts for the Invidious database by fetching them from the official GitHub repository and piping them into the running PostgreSQL instance.

```bash
export PGPASSWORD=kemal
for F in channels videos channel_videos users session_ids nonces annotations playlists playlist_videos; do
    curl -s https://raw.githubusercontent.com/iv-org/invidious/refs/heads/master/config/sql/$F.sql | \
        psql -h localhost -p 5432 -U kemal invidious
done
```

--------------------------------

### Create Podman Systemd Pod Unit for Invidious Application

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Establishes a systemd pod unit for Invidious, grouping all related containers and exposing the necessary port for external access.

```bash
cat > ~/.config/containers/systemd/invidious.pod <<EOF
[Pod]
PodName=invidious
PublishPort=3000:3000
[Install]
WantedBy=multi-user.target default.target
EOF
```

--------------------------------

### Clone Invidious Source Repository

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Clones the Invidious project source code from its GitHub repository and changes the current directory to the newly cloned 'invidious' folder.

```Shell
git clone https://github.com/iv-org/invidious
cd invidious
```

--------------------------------

### Create Podman Container for PostgreSQL

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Creates a Podman container for PostgreSQL, linking it to the 'videos' pod. It configures health checks, mounts data volumes, and sets environment variables for the database.

```bash
podman create --rm \
--pod videos \
--name postgres \
--label "io.containers.autoupdate=registry" \
--health-cmd='pg_isready -U $POSTGRES_USER -d $POSTGRES_DB' \
-v postgresdata:/var/lib/postgresql/data \
-v <INV-PATH>/invidious/config/sql:/config/sql:z \
-v <INV-PATH>/invidious/docker/init-invidious-db.sh:/docker-entrypoint-initdb.d/init-invidious-db.sh:z \
-e POSTGRES_DB=invidious \
-e POSTGRES_USER=kemal \
-e POSTGRES_PASSWORD=kemal \
docker.io/library/postgres:14
```

--------------------------------

### Launch Invidious Application

Source: https://docs.invidious.io/companion-installation/companion-installation

This command is used to start the Invidious application from its executable. It assumes the user is in the Invidious project directory.

```Shell
./invidious
```

--------------------------------

### Deploy and Enable Invidious Systemd Service

Source: https://docs.invidious.io/companion-installation/installation

Copies the provided `invidious.service` file to the systemd directory, then enables and immediately starts the Invidious service to ensure it runs automatically on boot and in the background.

```bash
cp /home/invidious/invidious/invidious.service /etc/systemd/system/invidious.service
systemctl enable --now invidious.service
```

--------------------------------

### Restart Podman Pod via Systemd

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Restarts the 'pod-videos.service' user service, which controls the 'videos' Podman pod, allowing for service updates or reinitialization.

```bash
systemctl --user restart pod-videos.service
```

--------------------------------

### Create Podman Pod for Videos

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Creates a new Podman pod named 'videos' and maps port 3000 from the host to port 3000 within the pod. This pod will host the Invidious and PostgreSQL containers.

```bash
podman pod create --name videos -p 3000:3000
```

--------------------------------

### Create Invidious Environment Configuration File

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Generates a systemd environment file (.env) for Invidious, containing database connection details, signature server address, and generated secrets.

```bash
cat > ~/.config/containers/systemd/invidious.env <<EOF
INVIDIOUS_DATABASE_URL="postgres://kemal:kemal@invidious-db:5432/invidious"
#INVIDIOUS_CHECK_TABLES=true
#INVIDIOUS_DOMAIN="inv.example.com"
INVIDIOUS_SIGNATURE_SERVER="invidious-sig-helper:12999"
INVIDIOUS_VISITOR_DATA="$VISITOR_DATA"
INVIDIOUS_PO_TOKEN="$PO_TOKEN"
INVIDIOUS_HMAC_KEY="$HMAC"
EOF
```

--------------------------------

### Generate Invidious YouTube Trusted Session Secrets

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Runs a utility container to generate VISITOR_DATA and PO_TOKEN secrets required for Invidious to interact with YouTube.

```bash
podman run quay.io/invidious/youtube-trusted-session-generator
```

--------------------------------

### Generate Systemd Services for Podman Pod

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Generates systemd user services for the 'videos' Podman pod and its containers, placing them in the user's systemd directory for lifecycle management.

```bash
cd ~
cp $(podman generate systemd --new --files --name videos) .config/systemd/user
```

--------------------------------

### Build and Configure Invidious on Linux

Source: https://docs.invidious.io/companion-installation/companion-installation

Switches to the 'invidious' user, navigates to the Invidious directory, builds the application using 'make', copies the example configuration, and provides instructions for adding Invidious Companion settings to `config/config.yml` before deploying the database schema.

```bash
su - invidious
cd invidious
make

# Configure config/config.yml as you like
cp config/config.example.yml config/config.yml

# edit config.yaml to include invidious companion

edit config/config.yaml

add:
invidious_companion:
  # URL used for the internal communication between invidious and invidious companion
  - private_url: "http://companion:8282"
  # (public) URL used for the communication between your browser and invidious companion
  # IF you are using a reverse proxy OR accessing invidious from an external IP then you NEED to change this value
  # Please consult for more doc: https://github.com/unixfox/invidious/blob/invidious-companion/config/config.example.yml#L57-L88
    public_url: "http://localhost:8282"
# IT is NOT recommended to use the same key as HMAC KEY. Generate a new key!
invidious_companion_key: "CHANGE_ME!!"

# Deploy the database
./invidious --migrate

exit
```

--------------------------------

### Set up Systemd Service for Invidious

Source: https://docs.invidious.io/companion-installation/companion-installation

Copies the Invidious systemd service file to the systemd directory and then enables and starts the service, ensuring Invidious runs automatically on system boot.

```bash
cp /home/invidious/invidious/invidious.service /etc/systemd/system/invidious.service
systemctl enable --now invidious.service
```

--------------------------------

### Complete Docker Compose example for Invidious with http3-ytproxy

Source: https://docs.invidious.io/companion-installation/improve-public-instance

A comprehensive `docker-compose.yml` file demonstrating the setup for Invidious, Invidious-refresh, and NGINX services. This example includes deployment replicas, restart policies, environment variables (like `INVIDIOUS_CONFIG` with database settings and `hmac_key`), health checks, logging options, and service dependencies.

```yaml
version: "3"
services:
    invidious:
        image: quay.io/invidious/invidious:latest
        deploy:
            replicas: 6
        restart: unless-stopped
        environment:
            INVIDIOUS_CONFIG: |
                channel_threads: 0
                feed_threads: 0
                db:
                    dbname: invidious
                    user: kemal
                    password: kemal
                    host: invidious-db
                    port: 5432
                check_tables: true
                # external_port:
                # domain:
                # https_only: false
                # statistics_enabled: false
                hmac_key: "CHANGE_ME!!"
        healthcheck:
            test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1
            interval: 30s
            timeout: 5s
            retries: 2
        logging:
            options:
                max-size: "1G"
                max-file: "4"
        depends_on:
           - invidious-db

    invidious-refresh:
        image: quay.io/invidious/invidious:latest
        restart: unless-stopped
        environment:
            INVIDIOUS_CONFIG: |
                db:
                    dbname: invidious
                    user: kemal
                    password: kemal
                    host: invidious-db
                    port: 5432
                    check_tables: true
                # external_port:
                # domain:
                # https_only: false
                # statistics_enabled: false
                hmac_key: "CHANGE_ME!!"
        healthcheck:
            test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1
            interval: 30s
            timeout: 5s
            retries: 2
        logging:
            options:
                max-size: "1G"
                max-file: "4"
        depends_on:
           - invidious-db

    nginx:
        image: nginx:latest
        restart: unless-stopped
```

--------------------------------

### Configure PostgreSQL Database for Invidious

Source: https://docs.invidious.io/companion-installation/installation

Enables and starts the PostgreSQL service, then creates a new database user ('kemal') and a database ('invidious') owned by this user. It is crucial to change the default password for security.

```bash
systemctl enable --now postgresql
sudo -i -u postgres
psql -c "CREATE USER kemal WITH PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml
createdb -O kemal invidious
exit
```

--------------------------------

### Install and Launch Invidious Companion

Source: https://docs.invidious.io/companion-installation/companion-installation

This snippet provides methods to set up Invidious Companion. It includes options to download a pre-compiled binary using `wget` or to compile it from source using `git clone` and `deno task compile`. Finally, it shows how to launch the companion with a required `SERVER_SECRET_KEY` environment variable.

```Shell
wget https://github.com/iv-org/invidious-companion???

# or compile it using https://docs.deno.com/runtime/
git clone https://github.com/iv-org/invidious-companion.git
deno task compile

# launch it
SERVER_SECRET_KEY=CHANGE_ME!!SAME_AS_INVIDIOUS_COMPANION_SECRET_KEY_FROM_INVIDIOUS_CONFIG ./invidious-companion
```

--------------------------------

### Reload Systemd Daemon for Podman Units

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Reloads the user's systemd daemon to register the newly created or modified Podman unit files, making them available for management.

```bash
systemctl --user daemon-reload
```

--------------------------------

### Clone Invidious Repository

Source: https://docs.invidious.io/companion-installation/companion-installation

Clones the Invidious GitHub repository and navigates into its directory. This is a prerequisite for accessing necessary configuration files and scripts for Docker Compose setup.

```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
```

--------------------------------

### Create Podman Systemd Container Unit for Invidious Database

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Defines a systemd unit file (.container) for the persistent Invidious PostgreSQL container, including environment variables, health checks, and pod association.

```bash
cat > ~/.config/containers/systemd/invidious-db.container <<EOF
[Container]
ContainerName=invidious-db
Environment=POSTGRES_DB=invidious POSTGRES_USER=kemal POSTGRES_PASSWORD=kemal
Image=docker.io/library/postgres:14
HealthCmd=pg_isready -h localhost -p 5432 -U kemal -d invidious
Notify=healthy
Pod=invidious.pod
Volume=invidious-db.volume:/var/lib/postgresql/data:Z
EOF
```

--------------------------------

### Update Invidious Docker Installation

Source: https://docs.invidious.io/companion-installation/companion-installation

This snippet provides commands to update an Invidious installation managed with Docker Compose. It pulls the latest images, recreates and starts containers, and prunes old Docker images to free up space.

```Shell
docker-compose pull
docker-compose up -d
docker image prune -f
```

--------------------------------

### Install and Run Invidious Companion

Source: https://docs.invidious.io/companion-installation/companion-installation

Provides options to download or compile Invidious Companion using Deno, demonstrates how to launch it manually with a required secret key, and mentions the ongoing development of a systemd service for background execution.

```bash
wget https://github.com/iv-org/invidious-companion???

# or compile it using https://docs.deno.com/runtime/
git clone https://github.com/iv-org/invidious-companion.git
deno task compile

# launch it manually
SERVER_SECRET_KEY=CHANGE_ME!!SAME_AS_INVIDIOUS_COMPANION_SECRET_KEY_FROM_INVIDIOUS_CONFIG ./invidious-companion

See more docs about the environment variables: https://github.com/iv-org/invidious-companion/wiki/Environment-variables

# OR create a new systemd service for running it in background
# TODO systemd service not yet available
# https://github.com/iv-org/invidious-companion/issues/3
sudo wget https://github.com/iv-org/invidious-companion/raw/refs/heads/master/systemd.service -O /etc/systemd/systemd/invidious-companion.service
sudo systemctl enable --now invidious.service
```

--------------------------------

### Update Podman Images and Prune Old Ones

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Updates all Podman containers configured for auto-update to their latest images and then removes any dangling or unused images to free up disk space.

```bash
podman auto-update
podman image prune -f
```

--------------------------------

### Install Invidious Dependencies on Debian/Ubuntu

Source: https://docs.invidious.io/companion-installation/installation

Installs necessary development libraries, database components, and fonts for Invidious on Debian or Ubuntu systems using `apt`.

```bash
sudo apt install libssl-dev libxml2-dev libyaml-dev libgmp-dev libreadline-dev postgresql librsvg2-bin libsqlite3-dev zlib1g-dev libpcre3-dev libevent-dev fonts-open-sans
```

--------------------------------

### Validate Podman Quadlet Systemd Unit Syntax

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Performs a dry run validation of the generated Podman quadlet unit files using quadlet -dryrun, ensuring correct syntax before daemon reload.

```bash
/usr/libexec/podman/quadlet -dryrun -user
```

--------------------------------

### Enable User Lingering for Persistent Services

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Enables user lingering, ensuring that user-specific systemd services, like the Podman pod service, continue to run even after the user logs out from the server.

```bash
loginctl enable-linger
```

--------------------------------

### Invidious Production Docker Compose Configuration

Source: https://docs.invidious.io/companion-installation/installation

This YAML configuration defines the Docker services for a production Invidious setup, including the `invidious` application, `inv_sig_helper`, and `invidious-db` (PostgreSQL). It specifies image versions, port mappings, environment variables (including placeholders for `visitor_data`, `po_token`, and `hmac_key`), health checks, and volume mounts for persistent data and database initialization scripts. This setup is optimized for deployment behind a reverse proxy.

```yaml
version: "3"
services:

  invidious:
    image: quay.io/invidious/invidious:latest
    # image: quay.io/invidious/invidious:latest-arm64 # ARM64/AArch64 devices
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      # Please read the following file for a comprehensive list of all available
      # configuration options and their associated syntax:
      # https://github.com/iv-org/invidious/blob/master/config/config.example.yml
      INVIDIOUS_CONFIG: |
        db:
          dbname: invidious
          user: kemal
          password: kemal
          host: invidious-db
          port: 5432
        check_tables: true
        signature_server: inv_sig_helper:12999
        visitor_data: "CHANGE_ME!!"
        po_token: "CHANGE_ME!!"
        # external_port:
        # domain:
        # https_only: false
        # statistics_enabled: false
        hmac_key: "CHANGE_ME!!"
    healthcheck:
      test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1
      interval: 30s
      timeout: 5s
      retries: 2
    logging:
      options:
        max-size: "1G"
        max-file: "4"
    depends_on:
      - invidious-db

  inv_sig_helper:
    image: quay.io/invidious/inv-sig-helper:latest
    init: true
    command: ["--tcp", "0.0.0.0:12999"]
    environment:
      - RUST_LOG=info
    restart: unless-stopped
    cap_drop:
      - ALL
    read_only: true
    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: kemal
      POSTGRES_PASSWORD: kemal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]

volumes:
  postgresdata:
```

--------------------------------

### Set Temporary Environment Variables for Invidious Secrets

Source: https://docs.invidious.io/companion-installation/community-installation-guide

Defines temporary shell environment variables for HMAC, VISITOR_DATA, and PO_TOKEN secrets, which will be used to generate the Invidious configuration file.

```bash
HMAC=$(openssl rand -base64 21)
VISITOR_DATA="ABCDEF%3D%3D" # notsecret
PO_TOKEN="MpOIfiljfsdljds-Lljfsdk-ojrdjXVs==" # notsecret
```

--------------------------------

### Install Invidious Dependencies on Arch Linux

Source: https://docs.invidious.io/companion-installation/installation

Installs essential development tools, image rendering libraries, PostgreSQL, and fonts required for Invidious on Arch Linux systems using `pacman`.

```bash
sudo pacman -S base-devel librsvg postgresql ttf-opensans
```

--------------------------------

### Configure PostgreSQL for Invidious on MacOS

Source: https://docs.invidious.io/companion-installation/companion-installation

Starts the PostgreSQL service using Homebrew, creates a default database, then creates a new database role 'kemal' with a password and a database 'invidious' owned by 'kemal', followed by importing various SQL schema files.

```bash
brew services start postgresql
createdb
psql -c "CREATE ROLE kemal WITH LOGIN PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml
createdb -O kemal invidious
psql invidious kemal < config/sql/channels.sql
psql invidious kemal < config/sql/videos.sql
psql invidious kemal < config/sql/channel_videos.sql
psql invidious kemal < config/sql/users.sql
psql invidious kemal < config/sql/session_ids.sql
psql invidious kemal < config/sql/nonces.sql
psql invidious kemal < config/sql/annotations.sql
psql invidious kemal < config/sql/playlists.sql
psql invidious kemal < config/sql/playlist_videos.sql
```

--------------------------------

### Install Invidious Dependencies on Debian/Ubuntu

Source: https://docs.invidious.io/companion-installation/companion-installation

Installs development libraries (SSL, XML, YAML, GMP, Readline, SQLite, Zlib, PCRE, Event), PostgreSQL, image rendering tools (librsvg2-bin), and Open Sans fonts for Invidious on Debian/Ubuntu systems using apt.

```bash
sudo apt install libssl-dev libxml2-dev libyaml-dev libgmp-dev libreadline-dev postgresql librsvg2-bin libsqlite3-dev zlib1g-dev libpcre3-dev libevent-dev fonts-open-sans
```

--------------------------------

### Install Invidious Dependencies on RHEL-based Systems

Source: https://docs.invidious.io/companion-installation/companion-installation

Installs development libraries (OpenSSL, Libevent, XML, YAML, GMP, Readline, SQLite, Zlib), PostgreSQL, image rendering tools (librsvg2-devel), GCC, and Open Sans fonts for Invidious on RHEL, Fedora, AlmaLinux, and RockyLinux using dnf.

```bash
sudo dnf install -y openssl-devel libevent-devel libxml2-devel libyaml-devel gmp-devel readline-devel postgresql librsvg2-devel sqlite-devel zlib-devel gcc  open-sans-fonts
```

--------------------------------

### Install Invidious Dependencies on RHEL-based Systems

Source: https://docs.invidious.io/companion-installation/installation

Installs required development libraries, database, and fonts for Invidious on RHEL, Fedora, AlmaLinux, or RockyLinux systems using `dnf`.

```bash
sudo dnf install -y openssl-devel libevent-devel libxml2-devel libyaml-devel gmp-devel readline-devel postgresql librsvg2-devel sqlite-devel zlib-devel gcc open-sans-fonts
```

--------------------------------

### Run Docker Compose in Production Mode

Source: https://docs.invidious.io/companion-installation/companion-installation

Executes the `docker compose up -d` command to start the Invidious and Invidious Companion services in detached mode, based on the configured `docker-compose.yml` file.

```bash
docker compose up -d
```

--------------------------------

### Update Manual Invidious Installation

Source: https://docs.invidious.io/companion-installation/companion-installation

This snippet outlines the steps to update a manually installed Invidious instance. It involves switching to the `invidious` user, navigating to the installation directory, pulling the latest changes from Git, recompiling the application, and restarting the `invidious.service`.

```Shell
su - invidious
cd invidious
git pull
make
exit
systemctl restart invidious.service
```

--------------------------------

### Docker Compose Configuration for Production

Source: https://docs.invidious.io/companion-installation/companion-installation

Defines the Docker Compose configuration for a production setup of Invidious, Invidious Companion, and PostgreSQL database. It includes service definitions, image references, port mappings, environment variables for configuration (including secret keys), health checks, logging, and volume mounts for persistent data and initialization scripts.

```yaml
version: "3"
services:

  invidious:
    image: quay.io/invidious/invidious:master
    # image: quay.io/invidious/invidious:master-arm64 # ARM64/AArch64 devices
    restart: unless-stopped
    # Remove "127.0.0.1:" if used from an external IP
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      # Please read the following file for a comprehensive list of all available
      # configuration options and their associated syntax:
      # https://github.com/iv-org/invidious/blob/master/config/config.example.yml
      INVIDIOUS_CONFIG: |
        db:
          dbname: invidious
          user: kemal
          password: kemal
          host: invidious-db
          port: 5432
        check_tables: true
        invidious_companion:
        # URL used for the internal communication between invidious and invidious companion
        # There is no need to change that except if Invidious companion does not run on the same docker compose file.
        - private_url: "http://companion:8282"
        # (public) URL used for the communication between your browser and invidious companion
        # IF you are using a reverse proxy OR accessing invidious from an external IP then you NEED to change this value
        # Please consult for more doc: https://github.com/unixfox/invidious/blob/invidious-companion/config/config.example.yml#L57-L88
        # And make sure to add the routes from the post install when using a reverse proxy!
          public_url: "http://localhost:8282"
        # IT is NOT recommended to use the same key as HMAC KEY. Generate a new key!
        # Use the key generated in the 2nd step
        invidious_companion_key: "CHANGE_ME!!"
        # external_port:
        # domain:
        # https_only: false
        # statistics_enabled: false
        # Use the key generated in the 2nd step
        hmac_key: "CHANGE_ME!!"
    healthcheck:
      test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1
      interval: 30s
      timeout: 5s
      retries: 2
    logging:
      options:
        max-size: "1G"
        max-file: "4"
    depends_on:
      - invidious-db

  companion:
    image: quay.io/invidious/invidious-companion:latest
    environment:
    # Use the key generated in the 2nd step
       - SERVER_SECRET_KEY=CHANGE_ME!!SAME_AS_INVIDIOUS_COMPANION_SECRET_KEY_FROM_INVIDIOUS_CONFIG
    restart: unless-stopped
    # Remove "127.0.0.1:" if used from an external IP
    ports:
      - "127.0.0.1:8282:8282"
    logging:
      options:
        max-size: "1G"
        max-file: "4"
    cap_drop:
      - ALL
    read_only: true
    # cache for youtube library
    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: kemal
      POSTGRES_PASSWORD: kemal
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]

volumes:
  postgresdata:
  companioncache:
```

--------------------------------

### Update Invidious Manual Installation

Source: https://docs.invidious.io/companion-installation/installation

Commands to update a manually installed Invidious instance. This involves pulling the latest code from Git, recompiling, and restarting the Invidious service.

```Shell
su - invidious
cd invidious
git pull
make
exit
systemctl restart invidious.service
```

--------------------------------

### Configure PostgreSQL for Invidious on Linux

Source: https://docs.invidious.io/companion-installation/companion-installation

Enables and starts the PostgreSQL service, then switches to the 'postgres' user to create a new database user 'kemal' with a specified password and a database 'invidious' owned by 'kemal'. It advises changing the default password.

```bash
systemctl enable --now postgresql
sudo -i -u postgres
psql -c "CREATE USER kemal WITH PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml
createdb -O kemal invidious
exit
```

--------------------------------

### Apply New Docker Compose Configuration

Source: https://docs.invidious.io/companion-installation/improve-public-instance

Commands to stop and then start the Docker Compose services, applying all the changes made to `docker-compose.yml` and `nginx.conf`. This step is crucial to activate the new multi-process Invidious setup with NGINX load balancing.

```bash
docker compose down
docker compose up
```

--------------------------------

### Install Invidious Dependencies on Arch Linux

Source: https://docs.invidious.io/companion-installation/companion-installation

Installs essential build tools, image rendering libraries (librsvg), PostgreSQL, and fonts (ttf-opensans) required for Invidious on Arch Linux using the pacman package manager.

```bash
sudo pacman -S base-devel librsvg postgresql ttf-opensans
```

--------------------------------

### Install Python Pyroute2 Library

Source: https://docs.invidious.io/companion-installation/ipv6-rotator

Provides commands to install the `python-pyroute2` library, another essential dependency for the IPv6 rotation script, tailored for different Linux distribution package managers.

```Shell
sudo apt install python3-pyroute2
```

```Shell
sudo dnf install python-pyroute2
```

```Shell
sudo yourpackagemanager install python-pyroute2
```

--------------------------------

### Install Invidious Dependencies on MacOS

Source: https://docs.invidious.io/companion-installation/companion-installation

Updates Homebrew and installs Crystal, PostgreSQL, ImageMagick, and librsvg, which are all necessary dependencies for running Invidious on macOS.

```bash
brew update
brew install crystal postgresql imagemagick librsvg
```

--------------------------------

### Install Python Requests Library

Source: https://docs.invidious.io/companion-installation/ipv6-rotator

Provides commands to install the `python-requests` library, a dependency for the IPv6 rotation script, across various Linux distributions using their respective package managers.

```Shell
sudo apt install python3-requests
```

```Shell
sudo dnf install python-requests
```

```Shell
sudo yourpackagemanager install python-requests
```

--------------------------------

### Update Invidious Docker Installation

Source: https://docs.invidious.io/companion-installation/installation

Commands to update an Invidious instance installed via Docker. This pulls the latest images, recreates containers, and prunes old images to free up space.

```Shell
docker-compose pull
docker-compose up -d
docker image prune -f
```

--------------------------------

### Clone the Smart IPv6 Rotator Repository

Source: https://docs.invidious.io/companion-installation/ipv6-rotator

Clones the official Smart IPv6 Rotator repository from GitHub to a desired location on your system, preparing for installation and configuration.

```shell
git clone https://github.com/iv-org/smart-ipv6-rotator.git
```

--------------------------------

### NGINX Reverse Proxy Configuration for Invidious with Let's Encrypt

Source: https://docs.invidious.io/companion-installation/nginx

A basic NGINX server block configuration for Invidious, including HTTP to HTTPS redirection, SSL setup with Let's Encrypt certificates, and proxying requests to the Invidious backend. Access logs are disabled, and error logs are set to critical level. Remember to replace `invidious.domain.tld` with your actual domain.

```Nginx
server {
    listen 80;
    listen [::]:80;
    listen 443 ssl;
    listen [::]:443 ssl;
        http2 on;

    server_name invidious.domain.tld;

    access_log off;
    error_log /var/log/nginx/error.log crit;

    ssl_certificate /etc/letsencrypt/live/invidious.domain.tld/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/invidious.domain.tld/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header Host $host;    # so Invidious knows domain
        proxy_http_version 1.1;     # to keep alive
        proxy_set_header Connection ""; # to keep alive
    }

    if ($https = '') { return 301 https://$host$request_uri; }  # if not connected to HTTPS, perma-redirect to HTTPS
}
```

--------------------------------

### GET /api/v1/popular API Endpoint

Source: https://docs.invidious.io/companion-installation/api

Fetches a list of popular short videos.

```APIDOC
Schema:
[
    {
        "type": "shortVideo",
        "title": String,
        "videoId": String,
        "videoThumbnails": [
            {
            "quality": String,
            "url": String,
            "width": Int32,
            "height": Int32
            }
        ],

        "lengthSeconds": Int32,
        "viewCount": Int64,

        "author": String,
        "authorId": String,
        "authorUrl": String,

        "published": Int64,
        "publishedText": String
    }
]
```

--------------------------------

### Configure Traefik Labels for Invidious Companion Service

Source: https://docs.invidious.io/companion-installation/companion-traefik

This snippet shows the Traefik labels required for the Invidious companion container within a Docker Compose setup. It enables Traefik, defines a host rule based on the server name, and includes specific paths (like `/latest_version`, `/api/manifest/dash/id/`, `/videoplayback*`) that are typically handled by the companion. It specifies 'web-sec' as the entrypoint, enables TLS with a 'le' certificate resolver, and sets the service port to 8282.

```YAML
...    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.invidious-companion.rule=Host(`<server_name>`) && (Path(`/latest_version`) || PathPrefix(`/api/manifest/dash/id/`) || PathPrefix(`/videoplayback*`))"
      - "traefik.http.routers.invidious-companion.entrypoints=web-sec"
      - "traefik.http.routers.invidious-companion.tls.certresolver=le"
      - "traefik.http.services.invidious-companion.loadbalancer.server.port=8282"
...
```

--------------------------------

### Install and Monitor Bandwidth with vnStat

Source: https://docs.invidious.io/companion-installation/hide-instance-behind-proxy-server

Instructions to install and use vnStat, a network traffic monitor, to track incoming (rx) and outgoing (tx) bandwidth consumption on a server. This is useful for assessing the bandwidth usage of your proxy server.

```Shell
apt install vnstat
```

```Shell
systemctl enable --now vnstat
```

```Shell
vnstat
```

--------------------------------

### Test HAProxy Setup with Curl

Source: https://docs.invidious.io/companion-installation/hide-instance-behind-proxy-server

This curl command allows testing the HAProxy setup by resolving a domain to the proxy server's IP address and making an HTTPS request. It helps verify if the proxy is correctly forwarding traffic.

```bash
curl https://yourdomain.com/ --resolve yourdomain.com:443:PUBLIC_IPV4_ADDRESS_OF_PROXY_SERVER
```

--------------------------------

### Configure Traefik Labels for Invidious Service

Source: https://docs.invidious.io/companion-installation/companion-traefik

This snippet shows the Traefik labels required for the Invidious container within a Docker Compose setup. It enables Traefik, defines a host rule based on the server name, specifies 'web-sec' as the entrypoint, enables TLS with a 'le' certificate resolver, and sets the service port to 3000. The rule explicitly excludes paths that are handled by the companion service.

```YAML
...    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.invidious.rule=Host(`<server_name>`) && !(Path(`/latest_version`) || PathPrefix(`/api/manifest/dash/id/`) || PathPrefix(`/videoplayback*`))"
      - "traefik.http.routers.invidious.entrypoints=web-sec"
      - "traefik.http.routers.invidious.tls.certresolver=le"
      - "traefik.http.services.invidious.loadbalancer.server.port=3000"
...
```

--------------------------------

### Create Invidious User and Clone Repository

Source: https://docs.invidious.io/companion-installation/installation

Creates a dedicated system user named 'invidious' with a home directory, then switches to this user to clone the official Invidious source code repository from GitHub.

```bash
useradd -m invidious
su - invidious
git clone https://github.com/iv-org/invidious
exit
```

--------------------------------

### Invidious Server Log Example

Source: https://docs.invidious.io/companion-installation/faq

This snippet illustrates the format of server logs generated by an Invidious instance, detailing HTTP requests, status codes, and response times for various endpoints like video watches, API searches, and image fetches.

```plaintext
2021-08-30 18:15:44 UTC [info] 200 GET /watch?v=GIAKHj9uJtM 781.21ms
2021-08-30 18:15:49 UTC [info] 200 GET /api/v1/search?q=Fly%20away 500.0ms
2021-08-30 18:15:49 UTC [info] 200 GET /vi/lJcqAzWFWLs/mqdefault.jpg 15.82ms
2021-08-30 18:15:49 UTC [info] 200 GET /vi/JoP_Tte7z7o/mqdefault.jpg 70.64ms
```

--------------------------------

### Invidious Reverse Proxy Configuration Parameters

Source: https://docs.invidious.io/companion-installation/installation

Essential configuration parameters for Invidious when served behind a reverse proxy. These settings ensure proper handling of HTTPS, domain names, external ports, and enable features like faster video notifications and unblocking captions for public instances.

```YAML
https_only: true
domain: domain.ext
external_port: 443
use_pubsub_feeds: true
use_innertube_for_captions: true
```

--------------------------------

### Create Invidious User and Clone Repository

Source: https://docs.invidious.io/companion-installation/companion-installation

Creates a dedicated system user named 'invidious' with a home directory, switches to this user, and then clones the Invidious GitHub repository into their home directory.

```bash
useradd -m invidious
su - invidious
git clone https://github.com/iv-org/invidious
exit
```

--------------------------------

### Caddy Reverse Proxy Configuration for Invidious Companion

Source: https://docs.invidious.io/companion-installation/companion-caddy

This Caddyfile configuration sets up a reverse proxy for an Invidious instance, including specific routing for the Invidious companion service. It assumes Caddy handles SSL certificate management and disables logging by default. Users must replace `<server_name>` with their actual domain.

```Caddyfile
https://<server_name> {

  @companion {
        path /latest_version
        path /api/manifest/dash/id/*
        path /videoplayback*
    }

  reverse_proxy @companion localhost:8282
  reverse_proxy localhost:3000

  log {
      output discard
  }
}
```

--------------------------------

### Generate YouTube Identity Tokens for Invidious

Source: https://docs.invidious.io/companion-installation/installation

This command generates `po_token` and `visitor_data` identities required for Invidious to pass YouTube's verification checks. It must be run on the same public IP address that is blocked by YouTube to ensure the generated tokens are valid for bypassing checks on blocked IPs. The generated tokens need to be copied for subsequent configuration in the `docker-compose.yml` file.

```bash
docker run quay.io/invidious/youtube-trusted-session-generator
```
Tokens:
Raw