# furtka-gateway starter stack

Zero-infra on-ramp: bundles its own Traefik + wg-easy alongside the
control-plane, for an operator who doesn't already run either. This is a
secondary path — if you already have Traefik and/or wg-easy running
(a common self-hosting setup), use the main repo's root `docker-compose.yaml`
+ `ops/deploy.sh` instead, which plugs into what you already have rather
than running a second copy. See the root `README.md`'s Prerequisites
checklist.

This stack always runs in `GATEWAY_MODE=single`, owns ports `80/tcp`,
`443/tcp`, and `51820/udp` on the host directly, and uses HTTP-01 certs
(no DNS provider needed) — the tradeoffs that make `single-parallel` mode
necessary elsewhere don't apply here, because this stack assumes nothing
else is already using those ports.

## Deploying on a VPS

1. Get a VPS with a static public IP, and point two A/AAAA records at it:
   one for `GATEWAY_PUBLIC_HOST` (the WireGuard endpoint) and one for
   `GATEWAY_CONTROL_PLANE_HOST` (the registration API — needs its own
   hostname since the response carries a WireGuard private key in
   plaintext JSON, so that call must go over HTTPS).
2. Run `./deploy.sh` from this directory and answer its prompts. It
   generates the wg-easy admin password hash, `GATEWAY_BOX_TOKEN`, and
   `GATEWAY_ADMIN_TOKEN`, writes `.env`, renders
   `traefik/static/traefik.active.yml` and
   `traefik/dynamic/control-plane.yml` from their tracked templates, runs
   `sudo ops/host-sysctls.sh` (wg-easy needs `net.ipv4.ip_forward=1` and
   `net.ipv4.conf.all.src_valid_mark` — see that script's comments for why
   Docker's own `sysctls:` key can't set these under `network_mode: host`),
   brings the stack up, runs `sudo ops/firewall.sh` (locks wg-easy's admin
   API off the public interface — `network_mode: host` means Docker itself
   can no longer do that automatically), and health-checks it.
3. Open `80/tcp`, `443/tcp`, `51820/udp` in whatever firewall/security
   group sits in front of the VPS.

Run `./deploy.sh --render-only` to just (re)write `.env` and the rendered
Traefik files without touching sysctls/compose/firewall — useful to inspect
what would be generated, or after hand-editing `.env`.

## Local dev

```bash
./deploy.sh --render-only
# GATEWAY_PUBLIC_HOST can be a LAN-reachable IP for a first smoke test.
docker compose up -d
curl http://127.0.0.1:8090/healthz
```

`ops/firewall.sh` and the `control-plane.yml` Traefik route are about
reaching this gateway from the real internet — skip both for local dev.

## Docker Swarm caveats

If deploying via `docker stack deploy` instead of `docker compose up`:
- `docker-compose.yaml`'s `build: ../../control_plane` doesn't work under
  Swarm at all — it only ever schedules pre-built, tagged images. Swarm
  falls back to the `image:` key on the same service instead, which CI
  keeps published to the registry on every push to `master` (tagged
  `latest` plus the short commit sha). Set `GATEWAY_CONTROL_PLANE_IMAGE` in
  `.env` first if you want a specific commit-sha tag rather than whatever
  `latest` currently points to.
- `docker stack deploy` does not read a `.env` file next to the compose
  file the way `docker compose up` does — `set -a; source .env; set +a`
  first, or the `${VAR}` substitutions come out empty. **Do not `source`
  `.env` directly if `WG_EASY_PASSWORD_HASH` is set** — bash expands `$$`
  (its own PID) while sourcing, silently corrupting the hash's doubled-`$`
  escaping. Export that one variable separately, unescaped, or set it
  directly on the `docker stack deploy` command line.
- `depends_on` is silently ignored by Swarm — harmless here, since
  `control-plane` only talks to wg-easy/Traefik lazily on the first real
  request, not at startup.