Traefik Installation Guide¶
Intro¶
When using MUSCLE alongside traefik, the application and all devices can be made available globally via the Internet with only a few steps.
Note
You will need a registered domain which you can use to reach MUSCLE via traefik.
You don’t need to worry about configuration when adding new devices, because the application will handle this for you. All you need to do is enable treafik in the application and setup the infrastructure as described below.
Understanding how it works¶
Once Traefik is enabled and a device is added with traefik support. MUSCLE creates a dynamic configuration file for it. Traefik automatically detects this file and creates a route to reach the device. From now on it is reachable from everywhere.
Note
In order to use traefik, it must be enabled in the application configuration.
Docker¶
The easiest way to use Traefik alongside MUSCLE is to use the their docker image.
Install docker on your system and do the following steps:
Create a directory for all the necessary configuration Inside this directory create a second one called
traefik-dynamic-configs(or something that fits you).
Note
This directory must be the same as in the MUSCLE application because the files inside this directory are created by it. So maybe the directory already exists.
create a file called
docker-compose.yml:
version: "3.2"
services:
reverse-proxy:
image: traefik:v2.3
restart: always
ports:
- 80:80
- 443:443
- 8080:8080
volumes:
# make the docker sock available to traefik so he can detect the muscle app and other containers enabled
- /var/run/docker.sock:/var/run/docker.sock
# mount the static configuration of traefik
- ${CONFIG_DIR}/traefik.yml:/etc/traefik/traefik.yml
# if you are using the certificate generation of traefik make sure to mount the certificate file outside
- ${CERTIFICATE_DIR}/acme.json:/etc/traefik/acme.json
# mount the configuration for the devices
- ${CONFIG_DIR}/traefik-dynamic-configs/:/etc/traefik/dynamic-configs/
On the same directory level create a file called
.env:
CONFIG_DIR=/path_to_config_dir
CERTIFICATE_DIR=/path_to_certificate_dir
Replace /path_* with the correct paths on your system.
Note
When using the certificate generation from traefik, the certificate file mounted must have permissions 600
sudo chmod 600 <PATH_TO_CERTIFICATE_DIR>/acme.json
Traefik Configuration¶
To make the traefik work, it must also be configured, read the traefik documentation about the static configuration.
A simple file configuration may look like this (<PATH_TO_CONFIG_DIR>/traefik.yml):
global:
checkNewVersion: true
sendAnonymousUsage: false
entryPoints:
web:
address: :80
websecure:
address: :443
# Enable the api -- should be disabled in production
api:
insecure: true
dashboard: true
providers:
file:
# Directory in which the dynamic configs for the devices, generated by the backend, are stored (traefik must be enabled).
# This is the mountpoint in the docker container - e.g to mount the configs generated by the backend add
# <PATH_TO_DIR_CONTAINING_FILES_OUTSIDE_DOCKER>:/etc/traefik/device-configs to the volumes section of docker-compose.yml
directory: /etc/traefik/dynamic-configs
# Look for changes or new files inside this directory
watch: true
docker:
# containers which shall be visible by traefik need to place -traefik.enable=true in the labels section
exposedByDefault: false
# Automatic Https certificate generation - if this is not present, traefik will create it's default cert
# To use this, your muscle application must be reachable under a registered domain
# certificatesResolvers:
# letsencrypt:
# acme:
# # server to test setup - since letsencrypt has a limited amount of requests per day
# # comment this out when finished with developing
# caServer: https://acme-staging-v02.api.letsencrypt.org/directory
# email: <YOUR_EMAIL>
# # file to store certificates in use a volume and make sure permissions are 600 - (sudo chmod 600 acme.json)
# storage: /etc/traefik/acme.json
# tlsChallenge: {}
# httpChallenge:
# entryPoint: web
# Optional log configuration
#log:
# level: ERROR
# filePath: "/var/log/traefik.log"
accesslog:
# Not adding a path will make traefik log to standard output and it can be watched with e.g. 'docker-compose logs --follow'
# filePath: "/var/log/traefik.access.log"
format: json
fields:
defaultMode: keep
headers:
defaultMode: keep
Note
For Traefik to detect the configuration automatically watch must be enabled in it’s configuration.
MUSCLE Configuration¶
For simplicity it’s recommended to use the muscle docker image alongside traefik. If you still prefer to install MUSCLE from source, read the traefik doc for how to make it work.
Using the docker image is quite simple. Generally the same configuration as described in muscle-docker can be used, which will lead to a docker-compose.yml like this:
version: "3.2"
services:
reverse-proxy:
image: traefik:v2.3
# ... docker-compose from above
muscle:
image: registry.gitlab.ti.bfh.ch/muscle/docker/application:latest
restart: always
depends_on:
- reverse-proxy
labels:
- traefik.enable=true
- traefik.http.routers.muscle-http.rule=HOST(`${MUSCLE_DOMAIN_NAME}`)
- traefik.http.routers.muscle-http.entrypoints=web
- traefik.http.routers.muscle-https.rule=HOST(`${MUSCLE_DOMAIN_NAME}`)
- treafik.http.routers.muscle-https.entrypoints=websecure
- treafik.http.routers.muscle-https.tls=true
# uncomment the following line when using the certificate resolver in the traefik.yml
# - treafik.http.routers.muscle-https.tls.certresolver=letsencrypt
volumes:
# mount the configuration for the devices - location on host must be the same as in the traefik servce
- ${CONFIG_DIR}/traefik-dynamic-configs/:/var/www/muscle-backend/traefik_devices/
environment:
- # ...
Note
Using MUSCLE with Traefik, requires the configuration of MUSCLE_DOMAIN_NAME.
However it is recommended to not change variables like this when using the docker image, since you can already adjust the path on the host (:code:`${CONFIG_DIR}/traefik-dynamic-configs/`) in the docker-compose.
Note
When mounting the volumes like the dynamic configurations, make sure to specify the correct path (/var/www/muscle-backend/traefik_devices/) when you change the path of the dynamic config directory (treafik_devices) with the variable TRAEFIK_OUTPUT_PATH.
However it is recommended to not change variables like this when using the docker image, since you can already adjust the path on the host (${CONFIG_DIR}/traefik-dynamic-configs/) in the docker-compose.
You can read more about this topic here
Labels¶
This section gives a brief introduction to the labels used in the docker-compose.yml this is a minimal working configuration, see the official traefik documentation for more.
- traefik.enable=true
Tell traefik to make this image accessible if providers.docker.exposedByDefault is false.
- traefik.http.routers.muscle-http< s >.rule=HOST(`${MUSCLE_DOMAIN_NAME}`)
The domain name over which this application is registered, this can also be an IP address if you want to use it internal.
- traefik.http.routers.muscle-http.entrypoints=< web | websecure >
The entry point for the rule. They must exists in the traefik.yml
- treafik.http.routers.muscle-https.tls=true
Tell muscle that this is https via tls and that it shall use a certificate.
- treafik.http.routers.muscle-https.tls.certresolver=letsencrypt
When you got a domain for your application, you can use a certificate resolver to create a certificate. Make sure it is configured in traefik.yml. If this label is not added, traefik will serve it’s default certificate.
Warning
It is important that you do not redirect http to https, since MUSCLE calls devices in the internal network directly via http. If you would force https, the devices can not be reached anymore because browsers would block these http requests. To register a device you must be in the same network as the application and the devices accessing the webpage via http. Once a device is registered with traefik, it can be reached with https.