feat: traefik bare metal routing docs

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