This site’s lab grew two services: FileBrowser on dl.hetsulab.tech and wg-easy (WireGuard) on vpn.hetsulab.tech. Both joined the same attach-mode compose (deploy/docker-compose.attach.yml) that already carried site, status and dash. This note is the record of what actually broke and what the fix was — every point below is a thing that cost a real failure first.

The two new services

dl:            # FileBrowser — share files over the web
  image: filebrowser/filebrowser:latest
  volumes: [ dl-files:/srv, dl-config:/config ]
  command: [ --database=/config/filebrowser.db, --root=/srv, --address=0.0.0.0, --port=80 ]
  labels: (traefik.enable, traefik.docker.network=appnet, router dl., certresolver letsencrypt, port 80)

vpn:           # wg-easy — WireGuard web UI
  image: ghcr.io/wg-easy/wg-easy:latest
  cap_add: [ NET_ADMIN, SYS_MODULE ]
  sysctls: [ net.ipv4.conf.all.src_valid_mark=1, net.ipv4.ip_forward=1 ]
  env_file: [ wgpass.env ]          # PASSWORD_HASH=<bcrypt>  (gitignored)
  environment: [ WG_HOST=vpn.hetsulab.tech ]
  ports: [ "51820:51820/udp" ]
  expose: [ "51821" ]               # the web UI
  labels: (router vpn., certresolver letsencrypt, port 51821)

The main service-changing lines are the WireGuard cap_add + sysctls (so the tunnel can create an interface and route), the UDP host port publish, and the admin password delivered through env_file — the subject of the first trap.

Trap 1 — wg-easy v14 rejected the plaintext PASSWORD

The first compose gave wg-easy a PASSWORD= environment variable. The container exited immediately:

Error: DO NOT USE PASSWORD ENVIRONMENT VARIABLE. USE PASSWORD_HASH INSTEAD.

Version 14 of wg-easy drops plaintext and wants a bcrypt hash. Generate one through the project’s own helper and give it to the container as PASSWORD_HASH:

docker run --rm ghcr.io/wg-easy/wg-easy:14 wgpw '<your password>'
# prints  PASSWORD_HASH='$2b$12$CoqPqCsPtcFO...'

Trap 2 — Compose ate the $ signs

The bcrypt hash is full of $2b$12$.... Put it in a compose environment block (or a .env line) and Docker Compose’s variable interpolation reads every $ as the start of a variable name — the hash got mangled, a random substring of it was reported as an unset variable, and the whole compose file failed to parse. Two compounding gotchas:

  • Interpolated values need each $ doubled ($$2b$$12$$...) — easy to get wrong, and it breaks again on the next shell where the variable isn’t set.
  • A :? required-var (${VPN_WEB_PASSWORD_HASH:?}) makes every compose command fail — even docker compose exec dl ... — because the entire file is interpolated before anything runs.

The clean fix was to stop routing the secret through interpolation at all: gitignore a small env_file (deploy/wgpass.env, chmod 600) that holds the literal value. Compose passes env_file lines to the container verbatim — no $$ escaping, no required-var, no per-shell export.

# deploy/wgpass.env  (gitignored)
PASSWORD_HASH=$2b$12$CoqPqCsPtcFO.Ab99xylBNOW4.Iu7OOA2/ZIboHN6/oyxca3MWo7fW

The rule that kept me for an hour: if a value contains $ and must not be re-interpolated, give it to Compose via env_file, not environment:.

Trap 3 — FileBrowser reset needed the server stopped

FileBrowser’s default login is admin/admin on a fresh database — but the running config had a different password, so I reset it from the CLI. First attempt failed with Error: timeout: the CLI and the running server were fighting for the same SQLite file. The fix was structural — stop the container, run the CLI, start it again:

docker compose -f docker-compose.attach.yml stop dl
docker compose -f docker-compose.attach.yml run --rm dl -d /config/filebrowser.db users ls
docker compose -f docker-compose.attach.yml run --rm dl -d /config/filebrowser.db users update 1 --password 'NewPass'
docker compose -f docker-compose.attach.yml start dl

Two details there: the -d is FileBrowser’s --database short flag, and you must not repeat filebrowser after run --rm dl — the image’s entrypoint is already the filebrowser binary, so the args go straight to it.

Trap 4 — the “down” timeout that wasn’t one

Mid-setup the site looked unreachable from Hostinger’s Web Terminal, which reported ERR_CONNECTION_TIMED_OUT on https://dash.hetsulab.tech. A probe from the public internet returned 200 for every service in the same minute. The Web Terminal runs inside the VPS’s own network and was dialling the VPS’s own public IP — most hosting networks don’t hairpin NAT, so reaching yourself by your public address times out. A “have you checked the firewall?” that wasn’t: the firewall was fine; it was self-access.

Also in the same pass

  • Uptime Kuma was pinned to the :1 tag — the stale v1.23 line that carries a patched critical RCE. Bumped to :2 (2.5.12 stable). The dashboard had no monitors yet, so the upgrade was risk-free.
  • The final inventory, all reachable over HTTPS with real Let’s Encrypt certs:
Host Serves
hetsulab.tech (www, lab route to it) the static site
status. Uptime Kuma 2.5.12
dash. Heimdall
vpn. wg-easy (WireGuard, UDP 51820)
dl. FileBrowser