From 1e5b4927e5ae1d542d51158eb995d4f4b5a8b1c5 Mon Sep 17 00:00:00 2001
From: Anders Betts <anders.betts@gmail.com>
Date: Fri, 18 Sep 2026 10:35:11 +0200
Subject: deploy: --dev hot-reloads the daemon via docker cp + SIGHUP

- bokfd re-execs its own binary on SIGHUP, closing listeners/db first
- scripts/deploy.sh --dev cross-builds and copies binaries into the
  running container, then verifies the reported version
---
 docs/DEPLOY.md   | 17 +++++++++++++++++
 docs/PROTOCOL.md |  5 ++++-
 docs/STATE.md    |  4 +++-
 3 files changed, 24 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/DEPLOY.md b/docs/DEPLOY.md
index 8862fab..2964a19 100644
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -50,6 +50,23 @@ to touch an already initialized database. Subsequent `scripts/deploy.sh`
 runs update the image, tag and compose file, restart the daemon and wait for
 the healthcheck.
 
+## Fast iteration (`--dev`)
+
+Normal deploys build an image and recreate the container. While developing,
+`scripts/deploy.sh --dev` skips the image entirely:
+
+- the gate (`make` + `make test`) still runs locally,
+- on an architecture mismatch the binaries are cross-compiled here
+  (`deploy/Dockerfile.cross`, ~20 s on a PC),
+- the binaries are copied into the running container with `docker cp`,
+- the daemon is reloaded with `SIGHUP`, which re-execs the binary in place
+  (in-memory sessions are lost, clients reconnect),
+- the version the daemon reports is verified against the tag.
+
+No image is built and the container is not recreated; a later normal deploy
+replaces the copied binaries. Use a descriptive tag, e.g.
+`scripts/deploy.sh --dev v0.2.0-rc1`.
+
 ## Deploying upgrades
 
 ```sh
diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md
index f282691..1baf607 100644
--- a/docs/PROTOCOL.md
+++ b/docs/PROTOCOL.md
@@ -488,4 +488,7 @@ beyond the session and calls nothing but public commands.
 | `allow_org_create` | `true` | any user may create an org |
 
 Container deployments mount the socket directory, database directory, backup
-and export directories as volumes; the daemon is otherwise stateless.
+and export directories as volumes; the daemon is otherwise stateless. On
+`SIGHUP` the daemon closes its listeners and database and re-executes its own
+binary in place (used by `scripts/deploy.sh --dev`); in-memory sessions are
+reset and clients reconnect.
diff --git a/docs/STATE.md b/docs/STATE.md
index 3cbe448..458833e 100644
--- a/docs/STATE.md
+++ b/docs/STATE.md
@@ -65,7 +65,9 @@ server/protocol/ledger only.
     come from a lego sidecar using INWX DNS-01 (`compose.yaml`). Externals
     get accounts/roles/tokens, never VPN access. `scripts/deploy.sh` builds
     locally and ships over SSH, or builds on the host when architectures
-    differ.
+    differ. `scripts/deploy.sh --dev` cross-compiles the binaries here and
+    hot-reloads the daemon (SIGHUP re-exec via `docker cp`), skipping the
+    image build and container recreate.
 
 ## Pending decisions
 
-- 
cgit v1.3