How to Install Invidious on a Server: Complete Self-Hosting Guide

You can install Invidious on a Linux server using three primary methods: compiling the Crystal source code manually, deploying via Docker Compose, or running the binary as a systemd service.

Invidious is an open-source, privacy-focused alternative front-end for YouTube written in Crystal. The iv-org/invidious repository provides all necessary components to self-host the application, including dependency installers, container definitions, and production service files. This guide covers each deployment path with specific file references from the source code.

Prerequisites

All installation methods require PostgreSQL for data persistence and either the Crystal compiler (for manual builds) or Docker (for containerized deployment).

• Crystal ≥ 1.9 – Required to compile the application from source
• PostgreSQL ≥ 13 – Stores user data, subscriptions, and video metadata
• System dependencies – libssl-dev, libxml2-dev, libyaml-dev, libgmp-dev, libevent-dev, libpcre3-dev, libreadline-dev, zlib1g-dev, and librsvg2-bin
• Git – For cloning the repository and resolving Crystal shards

The repository includes scripts/install-dependencies.sh to automate OS package installation. It detects your distribution (Debian, Ubuntu, Fedora, Arch) via /etc/os-release and installs the appropriate packages using apt, yum, pacman, or zypper.

sudo bash scripts/install-dependencies.sh

Method 1: Manual Source Build

This method compiles the invidious binary directly on your server, giving you full control over the build process.

Clone and Compile

First, clone the repository and build the executable using the provided Makefile:

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

The Makefile executes shards install --production to fetch Crystal dependencies and compiles the binary to ./invidious in the project root.

Configure the Database

Create a PostgreSQL database matching the structure expected by the application:

CREATE USER kemal WITH PASSWORD 'your_secure_password';
CREATE DATABASE invidious OWNER kemal;

Copy the example configuration and edit the database credentials:

cp config/config.example.yml config/config.yml

Edit config/config.yml to update the db block with your PostgreSQL host, user, password, and database name. Generate a secure hmac_key (20+ random characters) to protect CSRF tokens and PubSubHub signatures.

Start the Server

Launch the binary with your configuration file:

./invidious -c config/config.yml

By default, the server listens on port 3000.

Method 2: Docker Compose Deployment

Docker Compose provides the fastest deployment path by containerizing both Invidious and PostgreSQL.

Prepare the Environment

The repository root contains docker-compose.yml, which defines two services: the Invidious application and a Postgres container. The application image is built from docker/Dockerfile during the first run.

Copy or view the compose file, then edit the INVIDIOUS_CONFIG environment variable to include your database credentials and hmac_key:

environment:
  INVIDIOUS_CONFIG: |
    db:
      dbname: invidious
      user: kemal
      password: your_secure_password
      host: invidious-db
      port: 5432
    hmac_key: "your_random_key_here"

Launch the Stack

Start the services in detached mode:

docker compose up -d

Docker builds the image (running shards install --production inside the container), creates the PostgreSQL volume, and starts both containers. Verify deployment with curl http://localhost:3000.

Method 3: Systemd Service Setup

For production servers requiring automatic startup and process management, use the provided invidious.service unit file.

Install the Service

Copy the unit file from the repository to your systemd directory:

sudo cp invidious.service /etc/systemd/system/

Edit the file to match your installation paths. Adjust User, Group, and WorkingDirectory directives to point to where you cloned the repository (e.g., /opt/invidious):

[Service]
Type=simple
User=invidious
WorkingDirectory=/opt/invidious
ExecStart=/opt/invidious/invidious -c /opt/invidious/config/config.yml

Enable and Start

Reload systemd to recognize the new unit, then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now invidious

View logs using journalctl -u invidious or check the log file specified in your configuration.

Post-Installation Configuration

After installation, configure your reverse proxy and security settings for public access.

• Reverse Proxy – Configure Nginx or Apache to forward HTTPS traffic to http://127.0.0.1:3000. Set the domain and https_only fields in config/config.yml to match your public URL.
• Invidious Companion – For improved video streaming performance, enable the invidious_companion section in config/config.yml. This requires a separate companion binary to handle YouTube video delivery.
• Security – Ensure your hmac_key is cryptographically random. Use pwgen 20 1 or similar to generate this value before exposing the instance publicly.

Summary

• Manual builds offer maximum control using the Makefile and scripts/install-dependencies.sh, requiring Crystal ≥ 1.9 and PostgreSQL ≥ 13.
• Docker Compose provides the quickest setup via docker-compose.yml and docker/Dockerfile, automatically handling dependencies and database initialization.
• Systemd integration uses the provided invidious.service file for production-grade process management with automatic startup.
• Configuration is managed through config/config.yml (or the INVIDIOUS_CONFIG environment variable in Docker), requiring database credentials and a secure hmac_key.

Frequently Asked Questions

What are the minimum system requirements for Invidious?

Invidious requires modest resources: a Linux server with at least 1GB RAM and 10GB storage for the application and database. PostgreSQL ≥ 13 is mandatory, and if compiling from source, Crystal ≥ 1.9 must be installed. The application performs well on small VPS instances when properly configured with a reverse proxy.

Can I install Invidious without Docker?

Yes. The repository supports native compilation via the Makefile. Run scripts/install-dependencies.sh to install Crystal and system libraries, then execute make to build the ./invidious binary. This approach requires manual PostgreSQL setup using the SQL commands provided in the documentation.

Where do I configure database settings?

Database connection parameters live in config/config.yml (copied from config/config.example.yml). Update the db block with your PostgreSQL host, port, username, password, and database name. For Docker deployments, embed these values in the INVIDIOUS_CONFIG environment variable within docker-compose.yml.

How do I update Invidious to the latest version?

For manual installations, run git pull in the repository directory, then rebuild with make and restart the service. For Docker Compose deployments, pull the latest image with docker compose pull and restart the containers. Always back up your PostgreSQL database before updating.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}