iv-org/documentation
1
0
Fork 0
mirror of https://github.com/iv-org/documentation.git synced 2025-08-22 21:15:16 -04:00
Code Issues Projects Releases Packages Wiki Activity

Add QOL Improvements and Fix Issue #648

Browse source 
This PR adds some quality-of-life readability improvements and fixes #648.
This commit is contained in:
Stephen Fasciani 2025-05-22 20:16:31 -04:00 • committed by GitHub
parent ec79d88477
commit e0a395641e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 130 additions and 114 deletions
Download patch file Download diff file Expand all files Collapse all files

244
docs/companion-installation.md
View file

@ -2,13 +2,13 @@
After installation take a look at the [Post-install steps](#post-install-configuration). 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. >[!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 >[!WARNING]
> This documentation is temporary and will explain the process for testing Invidious companion. Invidious companion is currently in testing in the master branch.
> If you are using a reverse proxy then make sure to double check the [Post-install steps](#post-install-configuration) because you have new routes to add!
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 ## Hardware requirements
@ -35,116 +35,131 @@ Make sure to run the newer Docker Compose V2: https://docs.docker.com/compose/in
1. Execute these commands: 1. Execute these commands:
```bash
git clone https://github.com/iv-org/invidious.git ```bash
cd invidious 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) 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) >[!IMPORTANT]
pwgen 16 1 # for Invidious companion (invidious_companion_key) > The Invidious companion key must follow specific rules or Invidious will throw an HTTP 400 error when loading videos.
``` >
> It must:
> - Contain only alphanumeric characters (letters A-Z, a-z, and numbers 0-9).
> - Avoid special characters (e.g., #, !, @, etc.), as they will cause a 400 "Bad Request" error.
> - Be 16 characters long. No more, no less.
>
> We recommend generating the key using pwgen on Linux, e.g.:
>
> ```bash
> pwgen 16 1
> ```
3. Edit the docker-compose.yml with this content: 3. Edit the docker-compose.yml with this content:
```docker ```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 # image: quay.io/invidious/invidious:master-arm64 # ARM64/AArch64 devices
restart: unless-stopped restart: unless-stopped
# Remove "127.0.0.1:" if used from an external IP # 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"
environment: environment:
# Please read the following file for a comprehensive list of all available # Please read the following file for a comprehensive list of all available
# configuration options and their associated syntax: # configuration options and their associated syntax:
# https://github.com/iv-org/invidious/blob/master/config/config.example.yml # https://github.com/iv-org/invidious/blob/master/config/config.example.yml
INVIDIOUS_CONFIG: | INVIDIOUS_CONFIG: |
db: db:
dbname: invidious dbname: invidious
user: kemal user: kemal
password: kemal password: kemal
host: invidious-db host: invidious-db
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 # 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. # 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" - private_url: "http://companion:8282"
# (public) URL used for the communication between your browser and invidious companion # (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 # 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 # 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! # And make sure to add the routes from the post install when using a reverse proxy!
public_url: "http://localhost:8282" public_url: "http://localhost:8282"
# IT is NOT recommended to use the same key as HMAC KEY. Generate a new key! # 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 # Use the key generated in the 2nd step
- SERVER_SECRET_KEY=CHANGE_ME!!SAME_AS_INVIDIOUS_COMPANION_SECRET_KEY_FROM_INVIDIOUS_CONFIG invidious_companion_key: "CHANGE_ME!!"
restart: unless-stopped # external_port:
# Remove "127.0.0.1:" if used from an external IP # domain:
ports: # https_only: false
- "127.0.0.1:8282:8282" # statistics_enabled: false
logging: # Use the key generated in the 2nd step
options: hmac_key: "CHANGE_ME!!"
max-size: "1G" healthcheck:
max-file: "4" test: wget -nv --tries=1 --spider http://127.0.0.1:3000/api/v1/trending || exit 1
cap_drop: interval: 30s
- ALL timeout: 5s
read_only: true retries: 2
# cache for youtube library logging:
volumes: options:
- companioncache:/var/tmp/youtubei.js:rw max-size: "1G"
security_opt: max-file: "4"
- no-new-privileges:true depends_on:
- invidious-db
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"]
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: volumes:
postgresdata: - companioncache:/var/tmp/youtubei.js:rw
companioncache: security_opt:
``` - no-new-privileges:true
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. 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"]
4. Run the docker composition: 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.
5. Run the docker composition:
``` ```
docker compose up -d docker compose up -d
@ -216,15 +231,16 @@ exit
su - invidious su - invidious
cd invidious cd invidious
make make
```
#### Configure config/config.yml as you like
# Configure config/config.yml as you like ```cp config/config.example.yml config/config.yml```
cp config/config.example.yml config/config.yml
# edit config.yaml to include invidious companion #### edit config.yaml to include invidious companion
edit config/config.yaml ```nano config/config.yaml```
add: ```yaml
invidious_companion: invidious_companion:
# URL used for the internal communication between invidious and invidious companion # URL used for the internal communication between invidious and invidious companion
- private_url: "http://companion:8282" - private_url: "http://companion:8282"
@ -234,12 +250,12 @@ invidious_companion:
public_url: "http://localhost:8282" public_url: "http://localhost:8282"
# IT is NOT recommended to use the same key as HMAC KEY. Generate a new key! # IT is NOT recommended to use the same key as HMAC KEY. Generate a new key!
invidious_companion_key: "CHANGE_ME!!" invidious_companion_key: "CHANGE_ME!!"
# Deploy the database
./invidious --migrate
exit
``` ```
#### Deploy the database
```./invidious --migrate```
```exit```
#### Systemd service for Invidious #### Systemd service for Invidious