iv-org/documentation
1
0
Fork 0
mirror of https://github.com/iv-org/documentation.git synced 2025-07-27 00:35:54 -04:00
Code Issues Projects Releases Packages Wiki Activity

Merge b806efa844 into f9c6845eb4

Browse source
This commit is contained in:
Stephen Fasciani 2025-06-02 20:55:03 -03:00 • committed by GitHub
commit 08c1ce3227
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 215 additions and 324 deletions
Download patch file Download diff file Expand all files Collapse all files

403
docs/companion-installation.md
View file

@ -1,68 +1,49 @@
# Temporary installation guide for Invidious companion # Invidious Companion Installation Guide
After installation take a look at the [Post-install steps](#post-install-configuration). !!! warning This is a temporary guide for testing Invidious Companion, currently in the master branch. After installation, see Post-Install Configuration for additional steps, especially if using a reverse proxy.
Note: Any [PaaS](https://en.wikipedia.org/wiki/Platform_as_a_service) or [SaaS](https://en.wikipedia.org/wiki/Software_as_a_service) provider/software (Heroku, YunoHost, Repli...) are unsupported. Use them at your own risk. They **WILL** cause problems with Invidious and might even suspend your account for "abuse" since Invidious is heavy, bandwidth intensive and technically a proxy (and most providers don't like them). If you use one and want to report an issue, please mention which one you use. !!! danger Do not use PaaS/SaaS providers (e.g., Heroku, YunoHost) for Invidious. They may cause issues or suspend your account due to high bandwidth usage and proxy-like behavior. If reporting issues, specify your provider.
# WARNING about this doc ## Prerequisites
This documentation is temporary and will explain you how to test Invidious companion. Invidious companion is currently in testing in the master branch. !!! info **Hardware**: - **Minimum**: 20GB disk space, 512MB free RAM (\~2GB total), with regular restarts (see Post-Install Configuration). - **Public Instances**: 60GB disk space, 4GB RAM, 2 vCPUs, 200 Mbps link, 20TB traffic (unlimited preferred). - **Compilation**: 2.5GB free RAM (4GB recommended). Use a SWAP file/partition on low-RAM systems (e.g., cheap VPS) to reach ≥4GB. - **youtube-trusted-session-generator**: 1GB RAM on a machine with the same public IP as Invidious.
And if you are using a reverse proxy then make sure to read again the post install because you have new routes to add! ## Docker Installation
## Hardware requirements !!! note Invidious Docker images are hosted on Quay because it’s Free and Open Source, unlike Docker Hub.
Running Invidious requires at least 20GB disk space, 512MB of free RAM (so ~2G installed on the system), as long as it is restarted regularly, as recommended in the post-install configuration. Public instances should ideally have at least 60G disk space, 4GB of RAM, 2vCPU, a 200 mbps link and 20TB of traffic (no data cap/unlimited traffic is preferred). Ensure Docker Engine and Docker Compose V2 are installed. Verify by running `docker compose` (with a space).
Compiling Invidious requires at least 2.5GB of free RAM (We recommend to have at least 4GB installed). ### Steps
If you have less (e.g on a cheap VPS) you can setup a SWAP file or partition, so the combined amount is >= 4GB.
You need at least 1GB of RAM for the machine that will run the tool `youtube-trusted-session-generator` in the 1st step. Doesn't need to be the same machine as the one running Invidious, just a machine running on the same public IP address. 1. **Clone the Repository**:
## Docker
**The Invidious docker image is only [available on Quay](https://quay.io/repository/invidious/invidious) because, unlike Docker Hub, [Quay is Free and Open Source Software](https://github.com/quay/quay/blob/master/LICENSE). This is reflected in the `docker-compose.yml` file used in this walk-through.**
Ensure [Docker Engine](https://docs.docker.com/engine/install) and [Docker Compose](https://docs.docker.com/compose/install) are installed before beginning.
### Docker-compose method (production)
**This method uses the pre-built Docker image from quay**
Note: Currently the repository has to be cloned, this is because the `init-invidious-db.sh` file and the `config/sql` directory have to be mounted to the postgres container (See the volumes section in the docker-compose file below). This "problem" will be solved in the future.
Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/install/linux/. It should already be installed if you can successfully run the command `docker compose` (with a space between the two words).
1. Execute these commands:
```bash ```bash
git clone https://github.com/iv-org/invidious.git git clone https://github.com/iv-org/invidious.git
cd invidious cd invidious
``` ```
2. Generate two secret keys, one for Invidious (HMAC_KEY) and one for Invidious companion (invidious_companion_key) 2. **Generate Secret Keys**: Run these commands to create two unique alphanumeric keys:
```bash ```bash
pwgen 16 1 # for Invidious (HMAC_KEY) pwgen 16 1 # for Invidious (HMAC_KEY)
pwgen 16 1 # for Invidious companion (invidious_companion_key) pwgen 16 1 # for Invidious Companion (invidious_companion_key)
``` ```
3. Edit the docker-compose.yml with this content: !!! important Use `pwgen` to generate alphanumeric keys (letters and numbers only, no special characters) for compatibility with Invidious and Invidious Companion.
```docker 3. **Configure** `docker-compose.yml`: Create or edit `docker-compose.yml` with:
```yaml
version: "3" version: "3"
services: services:
invidious: invidious:
image: quay.io/invidious/invidious:master image: quay.io/invidious/invidious:master
# image: quay.io/invidious/invidious:master-arm64 # ARM64/AArch64 devices # Use quay.io/invidious/invidious:master-arm64 for ARM64/AArch64
restart: unless-stopped restart: unless-stopped
# Remove "127.0.0.1:" if used from an external IP
ports: ports:
- "127.0.0.1:3000:3000" - "127.0.0.1:3000:3000" # Change to "3000:3000" for direct access
environment: 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: | INVIDIOUS_CONFIG: |
db: db:
dbname: invidious dbname: invidious
@ -72,23 +53,10 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
port: 5432 port: 5432
check_tables: true check_tables: true
invidious_companion: invidious_companion:
# URL used for the internal communication between invidious and invidious companion private_url: "http://companion:8282"
# There is no need to change that except if Invidious companion does not run on the same docker compose file. public_url: "http://localhost:8282" # Update for reverse proxy/external IP
- private_url: "http://companion:8282" invidious_companion_key: "CHANGE_ME!!" # Use key from step 2
# (public) URL used for the communication between your browser and invidious companion hmac_key: "CHANGE_ME!!" # Use key from step 2
# 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: healthcheck:
test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1 test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1
interval: 30s interval: 30s
@ -104,12 +72,10 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
companion: companion:
image: quay.io/invidious/invidious-companion:latest image: quay.io/invidious/invidious-companion:latest
environment: environment:
# Use the key generated in the 2nd step - SERVER_SECRET_KEY=CHANGE_ME!! # Use same key as invidious_companion_key
- SERVER_SECRET_KEY=CHANGE_ME!!SAME_AS_INVIDIOUS_COMPANION_SECRET_KEY_FROM_INVIDIOUS_CONFIG
restart: unless-stopped restart: unless-stopped
# Remove "127.0.0.1:" if used from an external IP
ports: ports:
- "127.0.0.1:8282:8282" - "127.0.0.1:8282:8282" # Change to "8282:8282" for direct access
logging: logging:
options: options:
max-size: "1G" max-size: "1G"
@ -117,7 +83,6 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
cap_drop: cap_drop:
- ALL - ALL
read_only: true read_only: true
# cache for youtube library
volumes: volumes:
- companioncache:/var/tmp/youtubei.js:rw - companioncache:/var/tmp/youtubei.js:rw
security_opt: security_opt:
@ -142,254 +107,181 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
companioncache: companioncache:
``` ```
Note: This compose is made for a true "production" setup, where Invidious is behind a reverse proxy. If you prefer to directly access Invidious, replace `127.0.0.1:3000:3000` with `3000:3000` under the `ports:` section. 4. **Run Docker**:
4. Run the docker composition: - For **production** (pre-built image):
``` ```bash
docker compose up -d docker compose up -d
``` ```
- For **development** (build from source):
```bash
docker compose build
docker compose up -d
```
### Docker-compose method (development) !!! note The repository clone is required to mount `init-invidious-db.sh` and `config/sql` to the Postgres container. This will be simplified in the future.
**This method builds a Docker image from source**
```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
docker-compose up
```
## Manual Installation ## Manual Installation
### Linux ### Linux
#### Install Crystal 1. **Install Crystal**: Follow https://crystal-lang.org/install/ for your distribution. Use versions `1.10.x`, `1.11.x`, or `1.12.x` (untested `1.13.x` may work).
Follow the instructions for your distribution here: https://crystal-lang.org/install/ 2. **Install Dependencies**:
**Note:** Invidious currently supports the following Crystal versions: `1.10.x` / `1.11.x` / `1.12.x`. \ - **Arch Linux**:
Versions `1.9.x` and older are incompatible because we use features only present in the newer versions. \
Versions `1.13.x` should be compatible, however we did not test it.
#### Install the dependencies ```bash
sudo pacman -S base-devel librsvg postgresql ttf-opensans
```
- **Debian/Ubuntu**:
Arch Linux ```bash
```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
sudo pacman -S base-devel librsvg postgresql ttf-opensans ```
``` - **RHEL-based (RHEL, Fedora, AlmaLinux, RockyLinux)**:
Debian/Ubuntu ```bash
```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
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 ```
```
RHEL based and RHEL-like systems (RHEL, Fedora, AlmaLinux, RockyLinux...) 3. **Set Up Invidious**:
```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
```
#### Add an Invidious user and clone the repository ```bash
useradd -m invidious
su - invidious
git clone https://github.com/iv-org/invidious
cd invidious
make
cp config/config.example.yml config/config.yml
```
```bash 4. **Configure PostgreSQL**:
useradd -m invidious
su - invidious
git clone https://github.com/iv-org/invidious
exit
```
#### Set up PostgreSQL ```bash
systemctl enable --now postgresql
sudo -i -u postgres
psql -c "CREATE USER kemal WITH PASSWORD 'kemal';" # Use a strong password
createdb -O kemal invidious
exit
```
```bash 5. **Configure Invidious**: Edit `config/config.yml`:
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
```
#### Set up Invidious ```yaml
invidious_companion:
private_url: "http://companion:8282"
public_url: "http://localhost:8282" # Update for reverse proxy/external IP
invidious_companion_key: "CHANGE_ME!!" # Use key from pwgen
```
```bash Deploy the database:
su - invidious
cd invidious
make
# Configure config/config.yml as you like ```bash
cp config/config.example.yml config/config.yml ./invidious --migrate
exit
```
# edit config.yaml to include invidious companion 6. **Set Up Systemd**:
edit config/config.yaml ```bash
cp /home/invidious/invidious/invidious.service /etc/systemd/system/invidious.service
systemctl enable --now invidious.service
```
add: 7. **Set Up Invidious Companion**:
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 ```bash
./invidious --migrate git clone https://github.com/iv-org/invidious-companion.git
cd invidious-companion
deno task compile
SERVER_SECRET_KEY=CHANGE_ME!! ./invidious-companion # Use same key as invidious_companion_key
```
exit !!! info See environment variables: https://github.com/iv-org/invidious-companion/wiki/Environment-variables.
```
#### Systemd service for Invidious
```bash
cp /home/invidious/invidious/invidious.service /etc/systemd/system/invidious.service
systemctl enable --now invidious.service
```
#### Set up Invidious companion
```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
```
### MacOS ### MacOS
#### Install the dependencies 1. **Install Dependencies**:
```bash ```bash
brew update brew update
brew install crystal postgresql imagemagick librsvg brew install crystal postgresql imagemagick librsvg
``` ```
#### Clone the Invidious repository 2. **Set Up Invidious**:
```bash ```bash
git clone https://github.com/iv-org/invidious git clone https://github.com/iv-org/invidious
cd invidious cd invidious
``` make
cp config/config.example.yml config/config.yml
```
#### Set up PostgreSQL 3. **Configure PostgreSQL**:
```bash ```bash
brew services start postgresql brew services start postgresql
createdb createdb
psql -c "CREATE ROLE kemal WITH LOGIN PASSWORD 'kemal';" # Change 'kemal' here to a stronger password, and update `password` in config/config.yml psql -c "CREATE ROLE kemal WITH LOGIN PASSWORD 'kemal';" # Use a strong password
createdb -O kemal invidious createdb -O kemal invidious
psql invidious kemal < config/sql/channels.sql psql invidious kemal < config/sql/channels.sql
psql invidious kemal < config/sql/videos.sql psql invidious kemal < config/sql/videos.sql
psql invidious kemal < config/sql/channel_videos.sql psql invidious kemal < config/sql/channel_videos.sql
psql invidious kemal < config/sql/users.sql psql invidious kemal < config/sql/users.sql
psql invidious kemal < config/sql/session_ids.sql psql invidious kemal < config/sql/session_ids.sql
psql invidious kemal < config/sql/nonces.sql psql invidious kemal < config/sql/nonces.sql
psql invidious kemal < config/sql/annotations.sql psql invidious kemal < config/sql/annotations.sql
psql invidious kemal < config/sql/playlists.sql psql invidious kemal < config/sql/playlists.sql
psql invidious kemal < config/sql/playlist_videos.sql psql invidious kemal < config/sql/playlist_videos.sql
``` ```
#### Set up Invidious 4. **Configure and Run**: Edit `config/config.yml` as above, then:
```bash ```bash
make ./invidious
```
# Configure config/config.yml as you like 5. **Set Up Invidious Companion**: Follow the Linux steps for Invidious Companion setup.
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"
invidious_companion_key: "CHANGE_ME!!"
# launch invidious
./invidious
```
#### Set up Invidious companion
```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
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
```
### Windows ### Windows
Crystal, the programming language used by Invidious, [doesn't officially support Windows yet](https://github.com/crystal-lang/crystal/issues/5430) but you can still install Invidious: !!! warning Crystal lacks official Windows support (https://github.com/crystal-lang/crystal/issues/5430). Use one of these options: - Install Docker Desktop and follow the Docker Installation. - Use Windows Subsystem for Linux and follow the Linux steps. - Try Windows-specific Crystal builds, but these are untested.
- By installing [Docker desktop](https://docs.docker.com/desktop/install/windows-install/) and then following [our guide about Docker](#docker). ## Post-Install Configuration
- By installing [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/about) and then following [our guide about Linux](#linux).
- By installing [Windows-specific builds](https://github.com/crystal-lang/crystal/releases/) of Crystal. Be wary, as we don't currently have records of Invidious being tested on those "unsupported" builds yet.
## Post-install configuration: !!! info See the configuration guide for detailed options.
Detailed configuration available in the [configuration guide](./configuration.md). !!! danger Set a random `hmac_key` in `config/config.yml` using: `bash pwgen 20 1`
You must set a random generated value for the parameter `hmac_key:`! On Linux you can generate it using the command `pwgen 20 1`. !!! warning Restart Invidious at least daily (ideally hourly) to avoid issues.
Because of various issues, Invidious **must** be restarted often, at least once a day, ideally every hour. For reverse proxy setups, add these to `config/config.yml`:
If you use a reverse proxy, you **must** configure Invidious to properly serve request through it: ```yaml
https_only: true # Enable for HTTPS
domain: domain.ext # Your domain
external_port: 443 # For HTTPS
use_pubsub_feeds: true # Faster video notifications
use_innertube_for_captions: true # Unblock captions in datacenters
```
`https_only: true` : if you are serving your instance via https, set it to true !!! note Configure reverse proxy routes: - NGINX- Apache2- Caddy- Traefik
`domain: domain.ext`: if you are serving your instance via a domain name, set it here ## Updating Invidious
`external_port: 443`: if you are serving your instance via https, set it to 443 ### Docker
`use_pubsub_feeds: true`: if you are serving your instance on the internet, allow for faster notification of new videos ([detailed explanation](https://github.com/iv-org/invidious/blob/97c4165f55c4574efb554c9dae8d919d08da1cdd/config/config.example.yml#L409)).
`use_innertube_for_captions: true`: if you are serving a public instance or you are hosting Invidious in a datacenter, allow to unblock captions ([detailed explanation](https://github.com/iv-org/invidious/issues/2567#issuecomment-1727928996)).
AND make sure to add these new routes into your reverse proxy, example in various reverse proxy:
- [NGINX](./companion-nginx.md)
- [Apache2](./companion-apache2.md)
- [Caddy](./companion-caddy.md)
- [Traefik](./companion-traefik.md)
## Update Invidious
#### Updating a Docker install
```bash ```bash
docker-compose pull docker compose pull
docker-compose up -d docker compose up -d
docker image prune -f docker image prune -f
``` ```
#### Update a manual install ### Manual
```bash ```bash
su - invidious su - invidious
cd invidious cd invidious
@ -399,14 +291,13 @@ exit
systemctl restart invidious.service systemctl restart invidious.service
``` ```
## Usage: ## Usage
```bash ```bash
./invidious ./invidious
``` ```
## Log Rotation
#### Logrotate configuration
```bash ```bash
echo "/home/invidious/invidious/invidious.log { echo "/home/invidious/invidious/invidious.log {