Prepare v2 release

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:

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.

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.
+> 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.
-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".
+
+### 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:
 
@@ -211,34 +316,3 @@ http:
 ```
 
 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.

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...).

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``.