diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md index ade94ae..9e25d62 100644 --- a/docs/operators/handbook.md +++ b/docs/operators/handbook.md @@ -548,6 +548,73 @@ route requests after. You're free to make as many `$whatever.yml` files in your Please note that we have to hardcode `production` and `web-secure` which are typically configurable when not using `FILE_PROVIDER_DIRECTORY_ENABLED`. +## Using Traefik for docker-(swarm)-deployment without recipe +If you prefer to integrate your apps without recipe directly in docker swarm, you can do this by setting the respective traefik-labels and deploy your app using `docker stack deploy -c compose.yml example_com` (make sure of course, the STACK_NAME: example_com is not used by another abra-app). + +Example: + +1. create a `.env` yourself with the needed env-vars + +``` +DOMAIN=example.com +EXTRA_DOMAINS=', `www.example.com`' +LETS_ENCRYPT_ENV=production + +# the .env-vars needed in your compose-file +``` + +2. source this .env-file +``` +set -a +source .env +``` + +3. adapt your `compose.yml`.make sure your `compose.yml` has the necessary traefik-labels. __Attention:__ .env-vars won't be parsed to the "left hand", so you have to set `${STACK_NAME}`-vars of the traefik-labels used in recipes in your `compose.yml` manually: + +``` +services: + app: + # ... + deploy: + # .... + labels: + - "traefik.enable=true" + - "traefik.http.services.example_com.loadbalancer.server.port=80" + - "traefik.http.routers.example_com.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS})" + - "traefik.http.routers.example_com.entrypoints=web-secure" + - "traefik.http.routers.example_com.tls.certresolver=${LETS_ENCRYPT_ENV}" + # Redirect from EXTRA_DOMAINS to DOMAIN + - "traefik.http.routers.example_com.middlewares=example_com-redirect" + - "traefik.http.middlewares.example_com-redirect.redirectscheme.scheme=https" + - "traefik.http.middlewares.example_com-redirect.redirectscheme.permanent=true" +``` + +When starting your adaption from a docker-compose-file: be also aware, that not all compose-features are supported by docker swarm, and some parts need to be nested in `deploy`. + +Make also sure, you attach your app to the `proxy`-overlay network, so traefik may find it: + +``` +services: + app: + # ... + + networks: + - proxy + +networks: + proxy: + external: true +``` + +4. deploy your app ("stack") +``` +docker stack deploy -c compose.yml example_com +``` + +__Useful for troubleshooting:__ there is `docker service inspect`, so e.g. make sure via inspect, your .env-files where successfully read by docker swarm: `docker service inspect example_com` + +If your app/deployment may be useful for others: please consider creating a recipe for it. The necessary steps from here on are only a few ;) + ## Can I use Caddy instead of Traefik? Yes, it's possible although currently Quite Experimental! See