From ed1c15929d2eb2dbc6432986c26661bf1549964a Mon Sep 17 00:00:00 2001
From: Anders Betts <anders.betts@gmail.com>
Date: Thu, 17 Sep 2026 21:26:20 +0200
Subject: Add native TLS transport, TLS clients and lego cert sidecar

- bokfd: optional TLS listener (OpenSSL), certificate reload on change
- clients: tls:host:port targets with chain and host verification
- compose: port 8788 and an INWX/lego renewal sidecar
- Makefile: header dependency tracking (-MMD -MP)
---
 docs/DEPLOY.md | 47 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

(limited to 'docs/DEPLOY.md')

diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md
index 5def5df..8d36453 100644
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -15,9 +15,13 @@ State lives in two bind mounts next to `compose.yaml`:
 
 | Host path | Container | Contents |
 |---|---|---|
-| `var/db` | `/var/lib/bokfd` | SQLite database, `backup/`, `export/` |
+| `var/db` | `/var/lib/bokfd` | SQLite database, `backup/`, `export/`, `certs/` |
 | `var/run` | `/run/bokfd` | Unix socket (mode 0660, owned by uid 10001) |
 
+The `bokfd` service publishes port 8788 for the TLS listener; the `certs`
+sidecar renews the certificate with lego via INWX DNS-01. Plain TCP stays
+off (loopback-only if enabled); the Unix socket is for clients on the host.
+
 The database is a single SQLite file. Back up with `backup.snapshot`
 (`VACUUM INTO`) and point restic at `var/db/backup` — never at the live file.
 
@@ -112,6 +116,47 @@ The clients honor `BOKFD_SOCKET`; a host-installed client can also point at
 `var/run/bokfd.sock`, but that file is owned by uid 10001, so the host user
 must be in that group (or use `sudo`).
 
+## TLS and external users
+
+Put the ACME DNS credentials in the host's `.env` once (they are never
+committed):
+
+```sh
+LEGO_DOMAIN=bokf.makandra.eu
+LEGO_EMAIL=anders@makandra.eu
+INWX_USERNAME=...
+INWX_PASSWORD=...
+```
+
+Forward port 8788 on the router to the host. The `certs` sidecar obtains and
+renews the certificate into `var/db/certs/certificates/`; `bokfd` reloads it
+in place. On the very first `up`, `bokfd` may restart a few times until the
+certificate exists — check `docker compose logs certs`.
+
+Clients outside the LAN connect with the DNS name:
+
+```sh
+export BOKFD_SOCKET=tls:bokf.makandra.eu:8788
+bokftui
+```
+
+No CA override is needed with a public ACME certificate (the system trust
+store suffices); `BOKFD_TLS_CA=/path/ca.pem` exists for private CAs.
+
+To invite someone, create an account and give it only the role and org it
+needs — no VPN, no SSH:
+
+```sh
+docker compose exec -e BOKFD_PASSWORD='<owner-pw>' bokfd \
+    bokfctl --user admin user.create '{"username":"revisor", ...}'
+docker compose exec -e BOKFD_PASSWORD='<owner-pw>' bokfd \
+    bokfctl --user admin org.member_add '{"org":1,"username":"revisor","role":"viewer"}'
+```
+
+Agents use `token.create` instead of a password; tokens are scoped and
+revocable. Only the TLS port is forwarded, and every command still requires
+authentication (`meta` and `health` excepted).
+
 ## Mock company
 
 ```sh
-- 
cgit v1.3