iv-org/documentation
1
0
Fork 0
mirror of https://github.com/iv-org/documentation.git synced 2025-11-23 01:01:57 -05:00
Code Issues Projects Releases Packages Wiki Activity

chore: make companion officially supported in the installation guide (#663)

Browse source 
* chore: make companion officially supported in the installation guide

* doc: improve again

* docs: explain how to download binary for non docker user

* docs: inv-sig-helper => invidious companion
This commit is contained in:
Émilien (perso) 2025-09-14 00:12:16 +02:00 • committed by GitHub
parent db98664a22
commit 74e7a16c3b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
11 changed files with 127 additions and 528 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/companion-apache2.md
View file

@ -1,4 +1,4 @@
# Apache2 reverse proxy setup with Invidious companion
# Apache2 reverse proxy setup with Invidious companion direct traffic
- A very basic config, secured with Let's Encrypt. Any log is disabled by default. Do not forget to replace `ServerName` with your domain.
@ -12,12 +12,8 @@
ProxyRequests off
ProxyPass / http://127.0.0.1:3000/ nocanon
ProxyPassReverse / http://127.0.0.1:3000/
ProxyPass /latest_version http://127.0.0.1:8282/ nocanon
ProxyPassReverse /latest_version http://127.0.0.1:8282/
ProxyPass /api/manifest/dash/id/ http://127.0.0.1:8282/ nocanon
ProxyPassReverse /api/manifest/dash/id/ http://127.0.0.1:8282/
ProxyPass /videoplayback http://127.0.0.1:8282/ nocanon
ProxyPassReverse /videoplayback http://127.0.0.1:8282/
ProxyPass /companion http://127.0.0.1:8282 nocanon
ProxyPassReverse /companion http://127.0.0.1:8282
AllowEncodedSlashes on
@ -62,14 +58,9 @@ To make the VirtualHost config below actually work, you should as well:
ProxyPass / http://127.0.0.1:3000/ nocanon
ProxyPassReverse / http://127.0.0.1:3000/
ProxyPass /latest_version http://127.0.0.1:8282/ nocanon
ProxyPassReverse /latest_version http://127.0.0.1:8282/
ProxyPass /api/manifest/dash/id/ http://127.0.0.1:8282/ nocanon
ProxyPassReverse /api/manifest/dash/id/ http://127.0.0.1:8282/
ProxyPass /api/v1/captions/ http://127.0.0.1:8282/ nocanon
ProxyPassReverse /api/v1/captions/ http://127.0.0.1:8282/
ProxyPass /videoplayback http://127.0.0.1:8282/ nocanon
ProxyPassReverse /videoplayback http://127.0.0.1:8282/
# ONLY WHEN public_url uncommented (not default)! Invidious companion service
#ProxyPass /companion http://127.0.0.1:8282/ nocanon
#ProxyPassReverse /companion http://127.0.0.1:8282/
ProxyPreserveHost On
ProxyRequests Off
AllowEncodedSlashes On

11
docs/companion-caddy.md
View file

@ -1,4 +1,4 @@
# Caddy reverse proxy setup with Invidious companion
# Caddy reverse proxy setup with Invidious companion direct traffic
This is a very basic config, assuming that you're using Caddy to manage SSL certificates for you.
Any log is disabled by default. Do not forget to replace `server_name` with your domain.
@ -6,14 +6,7 @@ Any log is disabled by default. Do not forget to replace `server_name` with your
```
https://<server_name> {
@companion {
path /latest_version
path /api/manifest/dash/id/*
path /videoplayback*
/api/v1/captions/*
}
reverse_proxy @companion localhost:8282
reverse_proxy /companion localhost:8282
reverse_proxy localhost:3000
log {

422
docs/companion-installation.md
View file

@ -1,422 +0,0 @@
# Temporary installation guide for Invidious companion
After installation take a look at the [Post-install steps](#post-install-configuration).
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.
# WARNING about this doc
This documentation is temporary and will explain you how to test Invidious companion. Invidious companion is currently in testing in the master branch.
And if you are using a reverse proxy then make sure to read again the post install because you have new routes to add!
## Hardware requirements
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).
Compiling Invidious requires at least 2.5GB of free RAM (We recommend to have at least 4GB installed).
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.
## 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
git clone https://github.com/iv-org/invidious.git
cd invidious
```
2. Generate two secret keys, one for Invidious (HMAC_KEY) and one for Invidious companion (invidious_companion_key)
```bash
pwgen 16 1 # for Invidious (HMAC_KEY)
pwgen 16 1 # for Invidious companion (invidious_companion_key)
```
3. Edit the docker-compose.yml with this content:
```docker
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:
```
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 the docker composition:
```
docker compose up -d
```
### Docker-compose method (development)
**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
### Linux
#### Install Crystal
Follow the instructions for your distribution here: https://crystal-lang.org/install/
**Note:** Invidious currently supports the following Crystal versions: `1.10.x` / `1.11.x` / `1.12.x`. \
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
Arch Linux
```bash
sudo pacman -S base-devel librsvg postgresql ttf-opensans
```
Debian/Ubuntu
```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
```
RHEL based and RHEL-like systems (RHEL, Fedora, AlmaLinux, RockyLinux...)
```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
exit
```
#### Set up PostgreSQL
```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
```
#### Set up Invidious
```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
```
#### 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
#### Install the dependencies
```bash
brew update
brew install crystal postgresql imagemagick librsvg
```
#### Clone the Invidious repository
```bash
git clone https://github.com/iv-org/invidious
cd invidious
```
#### Set up PostgreSQL
```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
```
#### Set up Invidious
```bash
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"
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
cd invidious-companion
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
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:
- By installing [Docker desktop](https://docs.docker.com/desktop/install/windows-install/) and then following [our guide about Docker](#docker).
- 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:
Detailed configuration available in the [configuration guide](./configuration.md).
You must set a random generated value for the parameter `hmac_key:`! On Linux you can generate it using the command `pwgen 20 1`.
Because of various issues, Invidious **must** be restarted often, at least once a day, ideally every hour.
If you use a reverse proxy, you **must** configure Invidious to properly serve request through it:
`https_only: true` : if you are serving your instance via https, set it to true
`domain: domain.ext`: if you are serving your instance via a domain name, set it here
`external_port: 443`: if you are serving your instance via https, set it to 443
`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
docker-compose pull
docker-compose up -d
docker image prune -f
```
#### Update a manual install
```bash
su - invidious
cd invidious
git pull
make
exit
systemctl restart invidious.service
```
## Usage:
```bash
./invidious
```
#### Logrotate configuration
```bash
echo "/home/invidious/invidious/invidious.log {
rotate 4
weekly
notifempty
missingok
compress
minsize 1048576
}" | tee /etc/logrotate.d/invidious.logrotate
chmod 0644 /etc/logrotate.d/invidious.logrotate
```

6
docs/companion-nginx.md
View file

@ -1,4 +1,4 @@
# NGINX reverse proxy setup with Invidious companion
# NGINX reverse proxy setup with Invidious companion direct traffic
This is a very basic config, secured with Let's Encrypt. Any log is disabled by default. Do not forget to replace `server_name` with your domain.
@ -32,8 +32,8 @@ server {
proxy_pass http://127.0.0.1:3000;
}
# Invidious companion service (multiple paths, same backend)
location ~ ^/(latest_version|videoplayback|api/v1/captions|api/manifest/dash/id)/ {
# Invidious companion service
location /companion {
proxy_pass http://127.0.0.1:8282;
}
}

6
docs/companion-traefik.md
View file

@ -1,4 +1,4 @@
# Traefik reverse proxy setup with Invidious companion
# Traefik reverse proxy setup with Invidious companion direct traffic
This is a very basic config, assuming that you're using Traefik to manage SSL certificates for you, and Traefik is on the same server as the Invidious and companion container.
Do not forget to replace `<server_name>` with your domain.
@ -8,7 +8,7 @@ Do not forget to replace `<server_name>` with your domain.
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.invidious.rule=Host(`<server_name>`) && !(Path(`/latest_version`) || PathPrefix(`/api/manifest/dash/id/`) || PathPrefix(`/api/v1/captions/`) || PathPrefix(`/videoplayback`))"
- "traefik.http.routers.invidious.rule=Host(`<server_name>`) && !(Path(`/companion`))"
- "traefik.http.routers.invidious.entrypoints=web-sec"
- "traefik.http.routers.invidious.tls.certresolver=le"
- "traefik.http.services.invidious.loadbalancer.server.port=3000"
@ -19,7 +19,7 @@ Do not forget to replace `<server_name>` with your domain.
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.invidious-companion.rule=Host(`<server_name>`) && (Path(`/latest_version`) || PathPrefix(`/api/manifest/dash/id/`) || PathPrefix(`/api/v1/captions/`) || PathPrefix(`/videoplayback`))"
- "traefik.http.routers.invidious-companion.rule=Host(`<server_name>`) && (Path(`/companion`))"
- "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"

1
docs/devtools.md
View file

@ -64,7 +64,6 @@ Your browser can't resolve an external resource because the domain/hostname does
- Make sure you have correctly followed the post install [in the installation guide](./installation.md).
- Look for possible solutions in the GitHub issues of Invidious by searching for the error message: https://github.com/iv-org/invidious/issues
- If you are trying the new Invidious companion, make sure that public_url and base_url is correctly configured. Double check!
### C) Request with Status 500 or Status 400

162
docs/installation.md
View file

@ -7,12 +7,14 @@ Note: Any [PaaS](https://en.wikipedia.org/wiki/Platform_as_a_service) or [SaaS](
## Hardware requirements
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).
Running Invidious and Invidious companion requires at least 20GB disk space, 2GB of free RAM, 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).
Compiling Invidious requires at least 2.5GB of free RAM (We recommend to have at least 4GB installed).
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.
## **MIGRATION NEEDED (NEW)**: Invidious companion
Invidious companion replace both `inv-sig-helper` and `youtube-trusted-session-generator`. You don't need to execute `youtube-trusted-session-generator` anymore.
## Docker
@ -28,31 +30,19 @@ Note: Currently the repository has to be cloned, this is because the `init-invid
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).
??? warning "About po_token and visitor_data identities"
po_token known as Proof of Origin Token. This is an attestation token generated by a complex anti robot verification system created by Google named BotGuard/DroidGuard. It is used to confirm that the request is coming from a genuine device.
These identity tokens (po_token and visitor_data) generated in this tutorial will make your entire Invidious session more easily traceable by YouTube because it is tied to a unique identifier.
There is currently no official automatic tool to periodically change these tokens. This is working in progress but, for the time being, this is the solution the Invidious team is offering.
If you want to be less traceable, you can always script the process by changing the identities every X hour.
1. Generate po_token and visitor_data identities for passing all verification checks on YouTube side:
```
docker run quay.io/invidious/youtube-trusted-session-generator
```
You have to run this command on the same public IP address as the one blocked by YouTube. Not necessarily the same machine, just the same public IP address.
You will need to copy these two parameters in the third step.
Subsequent usage of this same token will work on the same IP range or even the same ASN. The point is to generate this token on a blocked IP as "unblocked" IP addresses seems to not generate a token valid for passing the checks on a blocked IP.
2. Execute these commands:
1. Execute these commands:
```bash
git clone https://github.com/iv-org/invidious.git
cd invidious
```
2. Generate two secret keys, one for Invidious (HMAC_KEY) and one for Invidious companion (invidious_companion_key)
```bash
pwgen 16 1 # for Invidious (HMAC_KEY)
pwgen 16 1 # for Invidious companion (invidious_companion_key)
```
3. Edit the docker-compose.yml with this content:
```docker
@ -63,6 +53,7 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
image: quay.io/invidious/invidious:latest
# image: quay.io/invidious/invidious:latest-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:
@ -77,13 +68,18 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
host: invidious-db
port: 5432
check_tables: true
signature_server: inv_sig_helper:12999
visitor_data: "CHANGE_ME!!"
po_token: "CHANGE_ME!!"
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/companion"
# 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
@ -97,16 +93,27 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
depends_on:
- invidious-db
inv_sig_helper:
image: quay.io/invidious/inv-sig-helper:latest
init: true
command: ["--tcp", "0.0.0.0:12999"]
companion:
image: quay.io/invidious/invidious-companion:latest
environment:
- RUST_LOG=info
# 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
# Uncomment only if you have configured "public_url" for Invidious companion
# Or if you want to use Invidious companion as an API in your program.
# 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
@ -126,6 +133,7 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
volumes:
postgresdata:
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.
@ -136,10 +144,10 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
docker compose up -d
```
### Docker-compose method (development)
**This method builds a Docker image from source**
**Playback won't work without Invidious companion configured.**
```bash
git clone https://github.com/iv-org/invidious.git
@ -152,42 +160,11 @@ docker-compose up
### Linux
#### Generate po_token and visitor_data identities
[Follow these instructions here on the official tool `youtube-trusted-session-generator`](https://github.com/iv-org/youtube-trusted-session-generator?tab=readme-ov-file#tutorial-without-docker)
These two parameters will be required for passing all verification checks on YouTube side and you will have to configure them in Invidious.
You have to run this command on the same public IP address as the one blocked by YouTube. Not necessarily the same machine, just the same public IP address.
You will need to copy these two parameters in the `config.yaml` file.
Subsequent usage of this same token will work on the same IP range or even the same ASN. The point is to generate this token on a blocked IP as "unblocked" IP addresses seems to not generate a token valid for passing the checks on a blocked IP.
??? warning "About po_token and visitor_data identities"
po_token known as Proof of Origin Token. This is an attestation token generated by a complex anti robot verification system created by Google named BotGuard/DroidGuard. It is used to confirm that the request is coming from a genuine device.
These identity tokens (po_token and visitor_data) generated in this tutorial will make your entire Invidious session more easily traceable by YouTube because it is tied to a unique identifier.
There is currently no official automatic tool to periodically change these tokens. This is working in progress but, for the time being, this is the solution the Invidious team is offering.
If you want to be less traceable, you can always script the process by changing the identities every X hour.
#### Run inv_sig_helper in background
[Follow these instructions here on the official tool `inv_sig_helper`](https://github.com/iv-org/inv_sig_helper?tab=readme-ov-file#building-and-running-without-docker) and run it in the background with systemd for example.
inv_sig_helper handle the "deciphering" of the video stream fetched from YouTube servers. As it is running untrusted code from Google themselves, make sure to isolate it by for example running it inside a LXC or locked down through systemd.
The following systemd service file can be used to run inv_sig_helper with systemd: https://github.com/iv-org/inv_sig_helper/blob/master/inv_sig_helper.service
#### Install Crystal
Follow the instructions for your distribution here: https://crystal-lang.org/install/
**Note:** Invidious currently supports the following Crystal versions: `1.12.x` / `1.13.x` / `1.14.x`. \
Versions `1.11.x` and older are incompatible because we use features only present in the newer versions. \
Versions `1.15.x` should be compatible, however we did not test it.
**Note:** Invidious currently supports the following Crystal versions: `1.14.x` / `1.15.x` / `1.16.x`.
#### Install the dependencies
@ -235,23 +212,52 @@ 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.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://localhost:8282/companion"
# 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
```
#### Systemd service
#### 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 from a binary release
# https://github.com/iv-org/invidious-companion/releases/tag/master
wget https://github.com/iv-org/invidious-companion/releases/download/master/invidious_companion-x86_64-unknown-linux-gnu.tar.gz
# 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
sudo wget https://github.com/iv-org/invidious-companion/raw/refs/heads/master/invidious-companion.service -O /etc/systemd/systemd/invidious-companion.service
sudo systemctl enable --now invidious.service
```
### MacOS
We recommend installing [Docker desktop](https://docs.docker.com/desktop/setup/install/mac-install/) and then following [our guide about Docker](#docker) which will make the installation easier.
@ -273,13 +279,13 @@ Take a look at the community installation guide: [here](./community-installation
## Post-install configuration:
### Highly recommended
Detailed configuration available in the [configuration guide](./configuration.md).
You must set a random generated value for the parameter `hmac_key:`! On Linux you can generate it using the command `pwgen 20 1`.
Because of various issues, Invidious **must** be restarted often, at least once a day, ideally every hour.
If you use a reverse proxy, you **must** configure Invidious to properly serve request through it:
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`.
2. Because of various issues, Invidious **must** be restarted often, at least once a day, ideally every hour.
3. If you use a reverse proxy, you **must** configure Invidious to properly serve request through it:
`https_only: true` : if you are serving your instance via https, set it to true
@ -291,6 +297,24 @@ If you use a reverse proxy, you **must** configure Invidious to properly serve r
`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)).
### Advanced (improve performance)
For performance reasons, you may configure Invidious companion to be served directly under your reverse proxy for serving the video streams.
This will greatly improve your playback when used by multiple users.
Uncomment `public_url` for the parameter `invidious_companion:` in Invidious config.yaml and configure it like this:
Configure the `public_url` to be the same as the domain used for Invidious or on a separate domain (if you want) with the path `/companion`.
Examples: `https://MYINVIDIOUSDOMAIN/companion` or `https://COMPANION.MYINVIDIOUSDOMAIN/companion`.
Then configure your reverse proxy:
- [NGINX](./companion-nginx.md)
- [Apache2](./companion-apache2.md)
- [Caddy](./companion-caddy.md)
- [Traefik](./companion-traefik.md)
## Update Invidious
#### Updating a Docker install

2
docs/invidious-companion.md
View file

@ -1,6 +1,6 @@
# Invidious companion documentation
If you are looking for the installation guide then please read [companion-installation](./companion-installation.md).
If you are looking for the installation guide then please read [installation](./installation.md).
If you are looking for extra documentation about Invidious companion then please visit: [https://github.com/iv-org/invidious-companion/wiki](https://github.com/iv-org/invidious-companion/wiki).

15
docs/traefik.md Normal file
View file

@ -0,0 +1,15 @@
# Traefik reverse proxy setup
This is a very basic config, assuming that you're using Traefik to manage SSL certificates for you, and Traefik is on the same server as the Invidious and companion container.
Do not forget to replace `<server_name>` with your domain.
**Invidious Setup**
```
...
labels:
- "traefik.enable=true"
- "traefik.http.routers.invidious.rule=Host(`<server_name>`)"
- "traefik.http.routers.invidious.entrypoints=web-sec"
- "traefik.http.routers.invidious.tls.certresolver=le"
- "traefik.http.services.invidious.loadbalancer.server.port=3000"
...

8
docs/youtube-errors-explained.md
View file

@ -39,16 +39,16 @@ YouTube is blocking the communication of Invidious to their servers.
### Solution(s)
First make sure that you are running the latest version of Invidious and you are using inv_sig_helper. Please see [the updated installation guide](./installation.md).
First make sure that you are running the latest version of Invidious and you are using Invidious companion. Please see [the updated installation guide](./installation.md).
After which you can try these solutions:
- Change your public IP address. Reboot your router or by configuring a proxy in Invidious: https://github.com/iv-org/invidious/blob/2150264d849771df8f15bab172ab6d87eeb80c55/config/config.example.yml#L176-L185
- Change your public IP address. Reboot your router or by configuring a proxy in Invidious companion (not **Invidious**): https://github.com/iv-org/invidious-companion/blob/b0fcfa49e21b708adcdf9fbf15c82c75cf0002a4/config/config.example.toml#L33
- If you have IPv6 on the computer hosting Invidious, you can try to rotate your IPv6 public address, tutorial available here: "[Rotate your IPv6 address for escaping YouTube blocking](./ipv6-rotator.md)"
All of these options do not guarantee you to bring back Invidious to working conditions. These are just advices for trying to unblock your Invidious instance from YouTube. Make sure to always specify any modification being done to your Invidious when reporting issues.
## Videoplayback URLs that returns 403 HTTP errors
## Videoplayback URLs returning 403 HTTP errors
### Error explained
@ -63,7 +63,7 @@ This error has different root causes:
### Solution(s)
First make sure that you are running the latest version of Invidious and you are using inv_sig_helper. Please see [the updated installation guide](./installation.md).
First make sure that you are running the latest version of Invidious and you are using Invidious companion. Please see [the updated installation guide](./installation.md).
After which you can try these solutions:

1
mkdocs.yml
View file

@ -23,7 +23,6 @@ nav:
- 'redirector.md'
- 'For Administrators':
- 'installation.md'
- 'invidious-companion.md'
- 'configuration.md'
- 'youtube-errors-explained.md'
- 'devtools.md'