KeyArgo
/
seedbox
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Prepare v2 release

This commit is contained in:
Jean Froment 2022-03-07 22:46:00 +01:00
parent 53f4d6ab87
commit 2b4bc46d5c
5 changed files with 120 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
config.sample.yaml
View File

@ -230,6 +230,7 @@ services:
- host: ${TRAEFIK_DOMAIN}
httpAuth: true
internalPort: 80
# Gluetun is the VPN client service.
- name: gluetun
enabled: false
traefik:

2
doc/UPGRADE_V2.md
View File

@ -8,7 +8,7 @@ Since there are some breaking changes and a configuration structure migration, a
* **Configuration change to new YAML format**
* Run ``config-updater.sh`` to migrate your old services.conf to the new config.yaml format.
* ⚠️ jq (v1.5+) and yq (v4+) are now requirements
* ⚠️ ``jq`` (v1.5+) and ``yq`` (v4+) are now requirements
* Easier feature switches
* If a service is missing, it won't be enabled by default like before. The config is now more declarative.
* Traefik routing rules are now dynamically generated in a file in Traefik config directory, so no more Docker labels. They became hard to maintain due to all possibilities caused by VPN support or custom files for example.

156
doc/configuration.md
View File

@ -1,5 +1,44 @@
# Seedbox configuration
## Table of content
* [General principles](#general-principles)
* [Configuration structure and parameters](#configuration-structure-and-parameters)
* [Environment variables](#environment-variables)
* [Add your own service](#add-your-own-service)
* [Particular case: Plex with Hardware Transcoding](#particular-case-plex-with-hardware-transcoding)
* [Integration with other services (custom Traefik config)](#integration-with-other-services-custom-traefik-config)
* [Disable HTTPS completely](#disable-https-completely)
* [VPN](#vpn)
* [Default mode - Wireguard custom](#default-mode---wireguard-custom)
* [Your own mode (VPN provider supported by gluetun)](#your-own-mode-vpn-provider-supported-by-gluetun)
* [How does VPN is handled?](#how-does-vpn-is-handled)
* [Make the services communicate with each other](#make-the-services-communicate-with-each-other)
* [How does the configuration work?](#how-does-the-configuration-work)
## General principles
Every service (Plex, Sonarr, Jackett, Nextcloud...) is defined in a dedicated file (in docker-compose format) in the [services](../services/) directory.
All your configuration such as:
* Which services must be enabled
* What docker-compose file they are using if a a particular one must be applied instead of the default one (which is the one with the same name as the service)
* Routing rules (example: ``sonarr.yourdomain.com`` for Sonarr)
* If http authentication must be enabled (example: *enable* for Sonarr, *disable* for Nextcloud has it has built-in authentication)
* Some other parameters (see below)
... is located in ``config.yaml``. If you are starting fresh, copy ``config.sample.yaml`` into ``config.yaml``. If you don't, on the first run, ``./run-seedbox.sh`` will copy the sample file for you.
Then, all your "sensitive" (or "personal") data configuration (passwords, usernames, domain name, paths on the machine for persistent data...) is located in ``.env`` file.
When running ``./run-seedbox.sh``:
* ``.env`` is loaded
* ``config.yaml`` is parsed, some checks are performed
* For each service, if enabled, Traefik rules are generated ([see this section](#how-does-the-configuration-work)) dynamically
* docker-compose commands (pull, up...) are executed against all relevant files
## Configuration structure and parameters
Almost the whole stack can be configured by using the main configuration item: ``config.yaml``.
@ -10,9 +49,9 @@ Here is what it looks like:
services:
# Name of the service
- name: traefik
# Flag indicating if the service will be created
# Flag indicating if the service will be created or not
enabled: true
# Define traefik behavior for this service
# Define traefik (reverse proxy) behavior for this service
traefik:
# Enable or disable Traefik routing. For example, if your service is a DB, disable Traefik.
enabled: true
@ -20,7 +59,7 @@ services:
rules:
# Host to match request. Any environment variable is supported here, as long as there are braces around it.
- host: traefik.${TRAEFIK_DOMAIN}
# Traefik service to match (if it is a particular one). Here the "api@internal" service is internal to Traefik (dashboard access).
# Traefik service to match (if it is a particular one). Here the "api@internal" service is internal to Traefik (dashboard access). If not specified, a "traefik service" with the same name as the docker service will be created.
service: api@internal
# Enable http authentication
httpAuth: true
@ -33,6 +72,7 @@ services:
enabled: true
rules:
- host: deluge.${TRAEFIK_DOMAIN}
# No service is defined here => a traefik service named "deluge" will be created automatically
httpAuth: true
# Internal container port on which we want to bind the Traefik routing
internalPort: 8112
@ -61,7 +101,7 @@ services:
- host: sonarr-unsecure.${TRAEFIK_DOMAIN}
httpAuth: true
internalPort: 8989
# Using this flag, sonarr-unsecure.domain.com (for example) will be accesisble ONLY via http protocol
# Using this flag, sonarr-unsecure.domain.com (for example) will be accessible ONLY via http protocol
httpOnly: true
# Another service with backend using https
- name: nextcloud
@ -126,10 +166,36 @@ services:
# ...
```
...and you're set!
...and you're set! Just run ``./run-seedbox.sh`` to apply configuration changes.
Please note that the ``customFile`` flag **MUST** be relative to the "services" directory, because in some cases, some alternatives yaml files for bundled services are provided in the services directory.
For example, in this repository is provided a custom "plex-hardware-transcoding.yaml" file, with all the necessary adaptations to make Plex run with hardware transcoding enabled. Just add the ``customFile: plex-hardware-transcoding.yaml`` field in the ``plex`` service and this file will be used, instead of the default "plex.yaml".
> Please note that the ``customFile`` flag **MUST** be relative to the "services" directory, because in some cases, some alternatives yaml files for bundled services are provided in the services directory. See the next section for more details.
### Particular case: Plex with Hardware Transcoding
This project provides a custom [plex-hardware-transcoding.yaml](../services/plex-hardware-transcoding.yaml) file, with all the necessary adaptations to make Plex run with hardware transcoding enabled.
Just add the ``customFile: plex-hardware-transcoding.yaml`` field in the ``plex`` service and this file will be used, instead of the default "plex.yaml":
```yaml
services:
# ...
- name: plex
enabled: true
vpn: false
# Here is the change: by default, without this flag, the applied file was "plex.yaml"
customFile: plex-hardware-transcoding.yaml
traefik:
enabled: true
rules:
- host: plex.${TRAEFIK_DOMAIN}
httpAuth: false
internalPort: 32400
# ...
```
Then, run ``./run-seedbox.sh`` to make these changes taken into account and the new container Plex will have hardware transcoding.
> Note that you also have to enable Hardware Transcoding in your Plex Server settings after the container has started.
## Integration with other services (custom Traefik config)
@ -157,9 +223,48 @@ http:
If you want to handle your certificates on a firewall or another reverse proxy somewhere else on your network, it is now possible.
You just have to set ``httpOnly: true`` on all your services in ``config.yaml``.
Then, make the machine which acts as reverse proxy (and handles certificates) points on every Traefik URL with the correpsonding certificate, or make a wildcard redirection, based on your reverse proxy.
Then, make the machine which acts as reverse proxy (and handles certificates) points on every Traefik URL with the corresponding certificate, or make a wildcard redirection, based on your reverse proxy.
## How does it work?
## VPN
In order to hide a service behind a VPN, just enable ``gluetun`` service.
By default, the file used is [gluetun.yaml](../services/gluetun.yaml), which is in "Wireguard custom" mode, meaning you must have somewhere a Wireguard server running and access to its client configuration. But you can add your own config to match your requirements. See sections below.
### Default mode - Wireguard custom
* Edit the ``.env`` file and replace the Wireguard variables with your own (take them in ``.env.sample``).
* Enable ``gluetun`` service.
* Enable vpn (``vpn: true``) on any service.
* Run ``./run-seedbox.sh``.
* The service now uses Wireguard. If gluetun is down or if the VPN link is broken, your service won't have any access to Internet.
### Your own mode (VPN provider supported by gluetun)
* Create a ``gluetun-custom.yaml`` in the [services/custom/](../services/custom/) directory. You can duplicate [this one](../services/gluetun.yaml) to avoid starting from scratch.
* Adapt it to your needs (variables, mode...) according to your provider.
* Add all variables you may need (used in your custom yaml file) in your ``.env`` file (replacing the wireguard ones).
* Edit your ``config.yaml`` and add ``customFile: custom/gluetun-custom.yaml`` in the ``gluetun`` section.
* Enable vpn (``vpn: true``) on any service.
* Run ``./run-seedbox.sh``.
* The service now uses your VPN by tunneling via gluetun container. If gluetun is down or if the VPN link is broken, your service won't have any access to Internet.
### How does VPN is handled?
Behind the scenes, the ``run-seedbox.sh`` script will mainly add 2 overrides when enabling VPN on a service:
* Adds a file in [services/generated/](../services/generated/) which adds a ``network_mode: gluetun`` for your service.
* Specify in Traefik rule that the backend host is gluetun instead of the service directly.
## Make the services communicate with each other
With docker-compose, all services are in the same Docker network (it is called ``traefik-network`` and is defined [here](../docker-compose.yaml)). Docker provides DNS resolution in the same network based on the name of the services, which act as hostnames.
So, for example, in order to setup Deluge in Sonarr, just add ``http://deluge:8112`` in the Download Clients settings section in Sonarr.
⚠️ If you are trying to contact a container which has ``vpn`` flag enabled, you will have to point your config to ``gluetun`` instead, which acts as relay to contact the service. So if Deluge is behind the VPN, add ``http://gluetun:8112`` in Sonarr instead.
## How does the configuration work?
Behind the scenes, the ``run-seedbox.sh`` script will parse your ``config.yaml`` file and will generate a Traefik dynamic configuration file, which looks like this:
@ -210,35 +315,4 @@ http:
- url: "https://nextcloud:443"
```
This file will be automatically placed in [traefik/custom/](../traefik/custom/) directory (mounted by Traefik container) so the config will dynamically apply. This file is updated on each ``run-seedbox.sh`` execution.
## VPN
In order to hide a service behind a VPN, just enable ``gluetun`` service.
By default, the file used is [gluetun.yaml](../services/gluetun.yaml), which is in "Wireguard custom" mode, meaning you must have somewhere a Wireguard server running and access to its client configuration. But you can add your own config to match your requirements. See sections below.
### Default mode - Wireguard custom
* Edit the .env and replace the Wireguard variables with your own (take them in ``.env.sample``).
* Enable ``gluetun`` service.
* Enable vn (``vpn: true``) on any service.
* Run ``./run-seedbox.sh``.
* The service now uses Wireguard. If gluetun is down or if the VPN link is broken, your service won't have any access to Internet.
### Your own mode (VPN provider supported by gluetun)
* Create a ``gluetun-custom.yaml`` in the [services/custom/](../services/custom/) directory. You can duplicate [this one](../services/gluetun.yaml) to avoid starting from scratch.
* Adapt it to your needs (variables, mode...) according to your provider.
* Add all variables you may need (used in your custom yaml file) in your ``.env`` file (replacing the wireguard ones).
* Edit your ``config.yaml`` and add ``customFile: custom/gluetun-custom.yaml`` in the ``gluetun`` section.
* Enable vpn (``vpn: true``) on any service.
* Run ``./run-seedbox.sh``.
* The service now uses your VPN by tunneling via gluetun container. If gluetun is down or if the VPN link is broken, your service won't have any access to Internet.
### How does VPN is handled?
Behind the scenes, the ``run-seedbox.sh`` script will mainly add 2 overrides when enabling VPN on a service:
* Adds a file in [services/generated/](../services/generated/) which adds a ``network_mode: gluetun`` for your service.
* Specify in Traefik rule that the backend host is gluetun instead of the service directly.
This file will be automatically placed in [traefik/custom/](../traefik/custom/) directory (mounted by Traefik container) so the config will dynamically apply. This file is updated on each ``run-seedbox.sh`` execution.

2
doc/traefik_v2.md
View File

@ -1,5 +1,7 @@
# September 2020 - Upgrade to Traefik v2 instructions
> This guide is useful if you already are using the seedbox but did not update before September 2020.
Before upgrading Traefik to version 2, please check the following:
- In this repo, Traefik v2 upgrade is as seamless as possible (same environment variables than before, out-of-the-box config file...).

2
services/generated/README.md
View File

@ -1,3 +1,3 @@
# Generated files
This directory contains all generated overrides files. They are in .gitignore.
This directory contains all generated overrides files. They are in .gitignore so there should be no conflict when running ``git pull``.