From 2b4bc46d5c86c27bca6545141b19411ed35a892a Mon Sep 17 00:00:00 2001 From: Jean Froment Date: Mon, 7 Mar 2022 22:46:00 +0100 Subject: [PATCH] Prepare v2 release --- config.sample.yaml | 1 + doc/UPGRADE_V2.md | 2 +- doc/configuration.md | 156 ++++++++++++++++++++++++++--------- doc/traefik_v2.md | 2 + services/generated/README.md | 2 +- 5 files changed, 120 insertions(+), 43 deletions(-) diff --git a/config.sample.yaml b/config.sample.yaml index c300c54..9eb973b 100644 --- a/config.sample.yaml +++ b/config.sample.yaml @@ -230,6 +230,7 @@ services: - host: ${TRAEFIK_DOMAIN} httpAuth: true internalPort: 80 + # Gluetun is the VPN client service. - name: gluetun enabled: false traefik: diff --git a/doc/UPGRADE_V2.md b/doc/UPGRADE_V2.md index d70766c..62877c0 100644 --- a/doc/UPGRADE_V2.md +++ b/doc/UPGRADE_V2.md @@ -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. diff --git a/doc/configuration.md b/doc/configuration.md index 6141952..b90d90e 100644 --- a/doc/configuration.md +++ b/doc/configuration.md @@ -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. \ No newline at end of file diff --git a/doc/traefik_v2.md b/doc/traefik_v2.md index a0de210..3b00b4f 100644 --- a/doc/traefik_v2.md +++ b/doc/traefik_v2.md @@ -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...). diff --git a/services/generated/README.md b/services/generated/README.md index d178d48..b2d4f84 100644 --- a/services/generated/README.md +++ b/services/generated/README.md @@ -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``.