diff --git a/docs/operators/handbook.md b/docs/operators/handbook.md index 2fc4611e..c6639c4a 100644 --- a/docs/operators/handbook.md +++ b/docs/operators/handbook.md @@ -328,7 +328,7 @@ If you need to run a command within a running container you can use `abra app ru ## How do I attach on a non-running container? -If you need to run a command on a container that won't start (eg. the container is stuck in a restart loop) you can temporarily disable its default entrypoint by setting it in `compose.yml` to something like ['tail', '-f', '/dev/null'], then redeploy the stack (with `--force --chaos` so you don't need to commit), then [get into the now running container](#how-do-i-attach-to-a-running-container), do your business, and when done revert the compose.yml change and redeploy again. +If you need to run a command on a container that won't start (eg. the container is stuck in a restart loop) you can temporarily disable its default entrypoint by setting it in `compose.yml` to something like ['tail', '-f', '/dev/null'], then redeploy the stack (with `--force --chaos` so you don't need to commit), then [get into the now running container](#how-do-i-attach-to-a-running-container), do your business, and when done revert the compose.yml change and redeploy again. ## Can I run Co-op Cloud on ARM? @@ -389,3 +389,90 @@ docker stack deploy -c compose.yml example_com `abra` makes all of this more cenvenient but other tooling could follow this approach. + +## Proxying apps outside of Co-op Cloud with Traefik? + +It's possible! It's actually always been possible but we just didn't have +spoons to investigate. Co-op Cloud can co-exist on the same server as bare +metal apps, non-swarm containers (plain `docker-compose up` deployments!), +Nginx installs etc. It's a bit gnarly with the networking but doable. + +Enable the following in your Traefik `$domain.env` configuration: + +``` +FILE_PROVIDER_DIRECTORY_ENABLED=1 +``` + +You must also have host mode networking enabled for Traefik: + +``` +COMPOSE_FILE="$COMPOSE_FILE:compose.host.yml" +``` + +And re-deploy your `traefik` app. You now have full control over the [file +provider](https://doc.traefik.io/traefik/providers/file/#directory) +configuration of Traefik. This also means you lost the defaults of the +[`file-provider.yml.tmpl`](./file-provider.yml.tmpl), so this is a more +involved approach. + +The main change is that there is now a `/etc/traefik/file-providers` volume +being watched by Traefik for provider configurations. You can re-enable the +recipe defaults by copying the original over to the volume (this assumes you've +deployed `traefik` already without `FILE_PROVIDER_DIRECTORY_ENABLED`, which is +required for the following command): + +``` +abra app run $your-traefik app \ + cp /etc/traefik/file-provider.yml /etc/traefik/file-providers/ +``` + +You don't need to re-deploy Traefik, it should automatically pick this up. + +You can route requests to a bare metal / non-docker service by making a +`/etc/traefik/file-providers/$YOUR-SERVICE.yml` and putting something like this in +it: + +```yaml +http: + routers: + myservice: + rule: "Host(`my-service.example.com`)" + service: "myservice" + entryPoints: + - web-secure + tls: + certResolver: production + + services: + myservice: + loadBalancer: + servers: + - url: "http://$YOUR-HOST-IP:8080/" +``` + +Where you should replace all instances of `myservice`. + +You must use your host level IP address (replace `$YOUR-HOST-IP` in the +example). With host mode networking, your deployment can route out of the swarm +to the host. + +If you're running a firewall (e.g. UFW) then it will likely block traffic from +the swarm to the host. You can typically add a specific UFW to route from the +swarm (typically, your `docker_gwbridge`) to the specific port of your bare +metal / non-docker app: + +``` +docker network inspect docker_gwbridge --format='{{( index .IPAM.Config 0).Gateway}}' +172.18.0.1 +ufw allow from 172.18.0.0/16 proto tcp to any port $YOUR-APP-PORT +``` + +Notice that we turn `172.18.0.1` into `172.18.0.0/16`. It's advised to open the +firewall on a port by port case to avoid expanding your attack surface. + +Traefik should handle the usual automagic HTTPS certificate generation and +route requests after. You're free to make as many `$whatever.yml` files in your +`/etc/traefik/file-providers` directory. It should Just Work ™ + + Please note that we have to hardcode `production` and `web-secure` which are + typically configurable when not using `FILE_PROVIDER_DIRECTORY_ENABLED`.