2026-11-21
Adding a file share and a VPN to the stack
FileBrowser on `dl.` and wg-easy WireGuard on `vpn.` joined the same attach-mode stack — and every one of the setup gotchas (bcrypt hash, Compose `env_file`, a database lock, a self-access timeout) is written down here.
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 — evendocker 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
:1tag — 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 |