Battle-tested a deployment of tuwunel

CORS headers are sorted out, if a bit necessarily permissive SERVER_NAME and DOMAIN can be different and still server /_matrix and /.well-known/matrix correctly
2026-02-17 23:12:31 -08:00
parent 32eedb5982
commit 3d0418163b
5 changed files with 67 additions and 98 deletions
--- a/.env.sample
+++ b/.env.sample
@ -3,11 +3,19 @@ DOMAIN=tuwunel.example.com
 LETS_ENCRYPT_ENV=production
 COMPOSE_FILE="compose.yml"

-## Secrets
-SECRET_REGISTRATION_TOKEN_VERSION=v1
+## The name of the matrix server, but not neccessarily the domain name it will
+## be accessed at. $SERVER_NAME will go in databases, including other servers'
+## databases if you federate, so this is harder to change compared to a DNS
+## record. Concretely,
+## - users created on this matrix server will be known as "@user:$SERVER_NAME"
+## - traefik will forward requests made to $DOMAIN or to $SERVER_NAME/_matrix
+##   to tuwunel.
+SERVER_NAME=example.com

 ## Federation
 ALLOW_FEDERATION=true
+TRUSTED_SERVERS=["matrix.org"]

 ## Registration
 ALLOW_REGISTRATION=true
+SECRET_REG_TOKEN_VERSION=v1
--- a/README.md
+++ b/README.md
@ -17,8 +17,9 @@

 ## Quick start

-* `abra app new tuwunel --secrets`
+* `abra app new tuwunel`
 * `abra app config <app-name>`
+* `abra app secret generate --all <app-name>` (note down reg\_token! Or insert your own)
 * `abra app deploy <app-name>`

 For more, see [`docs.coopcloud.tech`](https://docs.coopcloud.tech).
--- a/compose.yml
+++ b/compose.yml
@ -1,41 +1,71 @@
-# Tuwunel info gratefully cribbed from https://matrix-construct.github.io/tuwunel/deploying/docker-compose.for-traefik.yml
-
+# Gratefully cribbed from https://matrix-construct.github.io/tuwunel/deploying/docker-compose.for-traefik.yml
+---
 services:
-  web:
-    image: nginx:1.29.2
+  app:
+    image: jevolk/tuwunel:v1.5.1
+    volumes:
+      - db:/var/lib/tuwunel
    networks:
      - proxy
+    environment:
+      TUWUNEL_SERVER_NAME: '${SERVER_NAME}'
+      TUWUNEL_DATABASE_PATH: /var/lib/tuwunel
+      TUWUNEL_PORT: 6167
+      TUWUNEL_MAX_REQUEST_SIZE: 20000000 # in bytes, ~20 MB
+      TUWUNEL_ALLOW_REGISTRATION: $ALLOW_REGISTRATION
+      TUWUNEL_REGISTRATION_TOKEN_FILE: /run/secrets/reg_token
+      TUWUNEL_ALLOW_FEDERATION: '${ALLOW_FEDERATION}'
+      TUWUNEL_TRUSTED_SERVERS: '${TRUSTED_SERVERS}'
+      #TODO: expose TUWUNEL_LOG?
+      TUWUNEL_ADDRESS: 0.0.0.0
+
+      # We need some way to serve the client and server .well-known json. The simplest way is via the TUWUNEL_WELL_KNOWN
+      # variable / config option, there are multiple ways to do this, e.g. in the tuwunel.toml file, and in a separate
+      # see the override file for more information about delegation
+      TUWUNEL_WELL_KNOWN: |
+        {
+        client=https://$DOMAIN,
+        server=$DOMAIN:443
+        }
+    ulimits:
+      nofile:
+        soft: 1048567
+        hard: 1048567
    deploy:
      restart_policy:
        condition: on-failure
      labels:
+        - "coop-cloud.${STACK_NAME}.version=0.1.0+v1.5.1"
        - "traefik.enable=true"
-        - "traefik.http.services.${STACK_NAME}.loadbalancer.server.port=80"
-        - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS})"
+        - "traefik.http.services.${STACK_NAME}.loadbalancer.server.port=6167"
+        - "traefik.http.routers.${STACK_NAME}.middlewares=${STACK_NAME}"
        - "traefik.http.routers.${STACK_NAME}.entrypoints=web-secure"
        - "traefik.http.routers.${STACK_NAME}.tls.certresolver=${LETS_ENCRYPT_ENV}"
-        ## Edit the following line if you are using one, but not both, "Redirect" sections below
-        #- "traefik.http.routers.${STACK_NAME}.middlewares=${STACK_NAME}-redirectscheme,${STACK_NAME}-redirecthostname"
-        ## Redirect from EXTRA_DOMAINS to DOMAIN
-        # - "traefik.http.middlewares.${STACK_NAME}-redirecthostname.redirectregex.regex=^http[s]?://([^/]*)/(.*)"
-        # - "traefik.http.middlewares.${STACK_NAME}-redirecthostname.redirectregex.replacement=https://${DOMAIN}/$${2}"
-        # - "traefik.http.middlewares.${STACK_NAME}-redirecthostname.redirectregex.permanent=true"
-        ## Redirect HTTP to HTTPS
-        # - "traefik.http.middlewares.${STACK_NAME}-redirectscheme.redirectscheme.scheme=https"
-        # - "traefik.http.middlewares.${STACK_NAME}-redirectscheme.redirectscheme.permanent=true"
-        ## When you're ready for release, run "abra recipe sync <name>" to set this
-        - "coop-cloud.${STACK_NAME}.version="
-        ## Enable backups: https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-configure-backuprestore
-        # TODO: write a pg_backup.sh that checkpoints the database
+        # Serve ${DOMAIN}, but also /_matrix and /.well-known/matrix for ${SERVER_NAME} if it's different.
+        - "traefik.http.routers.${STACK_NAME}.rule=Host(`${DOMAIN}`${EXTRA_DOMAINS}) || (Host(`${SERVER_NAME}`) && (PathPrefix(`/_matrix`) || PathPrefix(`/.well-known/matrix`)))"
+        # Redirect HTTP to HTTPS
+        - "traefik.http.middlewares.${STACK_NAME}-redirectscheme.redirectscheme.scheme=https"
+        - "traefik.http.middlewares.${STACK_NAME}-redirectscheme.redirectscheme.permanent=true"
+        # Overly permissive to allow web-hosted clients from other domains
+        - "traefik.http.middlewares.${STACK_NAME}.headers.accesscontrolalloworiginlist=*"
+        - "traefik.http.middlewares.${STACK_NAME}.headers.accesscontrolallowmethods=GET,OPTIONS,PUT"
+        - "traefik.http.middlewares.${STACK_NAME}.headers.accesscontrolallowheaders=*"
+        - "traefik.http.middlewares.${STACK_NAME}.headers.accesscontrolmaxage=100"
+        - "traefik.http.middlewares.${STACK_NAME}.headers.addvaryheader=true"
+        ## TODO: test and enable backups: https://docs.coopcloud.tech/maintainers/handbook/#how-do-i-configure-backuprestore
        # - "backupbot.backup=true"
        # - "backupbot.backup.path=/some/path"
-    healthcheck:
-      test: ["CMD", "curl", "-f", "http://${STACK_NAME}_app:8008/health"]
-      interval: 30s
-      timeout: 10s
-      retries: 10
-      start_period: 1m
+    secrets:
+      - reg_token
+
+secrets:
+  reg_token:
+    name: ${STACK_NAME}_reg_token_${SECRET_REG_TOKEN_VERSION}
+    external: true

 networks:
  proxy:
    external: true
+
+volumes:
+  db:
--- a/docker-compose.for-traefik.yml
+++ b/docker-compose.for-traefik.yml
@ -1,44 +0,0 @@
-# tuwunel - Behind Traefik Reverse Proxy
-# Gratefully cribbed from https://matrix-construct.github.io/tuwunel/deploying/docker-compose.for-traefik.yml
-
-services:
-  app:
-    ### If you already built the conduduwit image with 'docker build' or want to use the Docker Hub image,
-    ### then you are ready to go.
-    image: jevolk/tuwunel:latest
-    restart: unless-stopped
-    volumes:
-      - db:/var/lib/tuwunel
-      #- ./tuwunel.toml:/etc/tuwunel.toml
-    networks:
-      - proxy
-    environment:
-      TUWUNEL_SERVER_NAME: ${DOMAIN}
-      TUWUNEL_DATABASE_PATH: /var/lib/tuwunel
-      TUWUNEL_PORT: 6167 # should match the loadbalancer traefik label
-      TUWUNEL_MAX_REQUEST_SIZE: 20000000 # in bytes, ~20 MB
-      TUWUNEL_ALLOW_REGISTRATION: ${ALLOW_REGISTRATION}
-      TUWUNEL_REGISTRATION_TOKEN_FILE: '/run/secrets/regtoken' # A registration token is required when registration is allowed.
-      #TUWUNEL_YES_I_AM_VERY_VERY_SURE_I_WANT_AN_OPEN_REGISTRATION_SERVER_PRONE_TO_ABUSE: 'true'
-      TUWUNEL_ALLOW_FEDERATION: ${ALLOW_FEDERATION}
-      TUWUNEL_TRUSTED_SERVERS: '["matrix.org"]'
-      #TUWUNEL_LOG: warn,state_res=warn
-      TUWUNEL_ADDRESS: 0.0.0.0
-      #TUWUNEL_CONFIG: '/etc/tuwunel.toml' # Uncomment if you mapped config toml above
-
-      # We need some way to serve the client and server .well-known json. The simplest way is via the TUWUNEL_WELL_KNOWN
-      # variable / config option, there are multiple ways to do this, e.g. in the tuwunel.toml file, and in a separate
-      # see the override file for more information about delegation
-      TUWUNEL_WELL_KNOWN: |
-        {
-        client=https://${DOMAIN},
-        server=${DOMAIN}:443
-        }
-    #cpuset: "0-4" # Uncomment to limit to specific CPU cores
-    ulimits: # tuwunel uses quite a few file descriptors, and on some systems it defaults to 1024, so you can tell docker to increase it
-      nofile:
-        soft: 1048567
-        hard: 1048567
-
-volumes:
-  db:
--- a/docker-compose.override.yml
+++ b/docker-compose.override.yml
@ -1,26 +0,0 @@
-# tuwunel - Traefik Reverse Proxy Labels
-# Generously cribbed from https://matrix-construct.github.io/tuwunel/deploying/docker-compose.override.yml
-
-services:
-  app:
-    labels:
-      - "traefik.enable=true"
-      - "traefik.docker.network=proxy"
-
-      #- "traefik.http.routers.to-tuwunel.rule=Host(`${DOMAIN}`)"  # Change to the address on which tuwunel is hosted
-      #- "traefik.http.routers.to-tuwunel.tls=true"
-      #- "traefik.http.routers.to-tuwunel.tls.certresolver=letsencrypt"
-      #- "traefik.http.routers.to-tuwunel.middlewares=cors-headers@docker"
-      #- "traefik.http.services.to_tuwunel.loadbalancer.server.port=6167"
-
-      - "traefik.http.middlewares.cors-headers.headers.accessControlAllowOriginList=*"
-      - "traefik.http.middlewares.cors-headers.headers.accessControlAllowHeaders=Origin, X-Requested-With, Content-Type, Accept, Authorization"
-      - "traefik.http.middlewares.cors-headers.headers.accessControlAllowMethods=GET, POST, PUT, DELETE, OPTIONS"
-
-      # TODO cleanup comments
-      # If you want to have your account on <DOMAIN>, but host tuwunel on a subdomain,
-      # you can let it only handle the well known file on that domain instead
-      - "traefik.http.routers.to-matrix-wellknown.rule=Host(`${DOMAIN}`) && PathPrefix(`/.well-known/matrix`)"
-      - "traefik.http.routers.to-matrix-wellknown.tls=true"
-      - "traefik.http.routers.to-matrix-wellknown.tls.certresolver=letsencrypt"
-      - "traefik.http.routers.to-matrix-wellknown.middlewares=cors-headers@docker"