sam/ai-resume
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 3: dual bind per Sam's decision (DoD 3 amended, DoD 1/4/8 re-evidenced)

Browse Source 
Sam answered the bind question on AUD-133 (2026-10-26):
"A - dual bind: 127.0.0.1:8096 and 192.168.20.13:8096".

- docker-compose: publish 127.0.0.1 and ${APP_LAN_IP:-192.168.20.13}, never 0.0.0.0
- deploy.sh: carry APP_LAN_IP into the release .env, --lan-ip flag, health gate
  now requires /healthz 200 on loopback AND the LAN address
- rehearse.sh: assert both binds, no wildcard, LAN reachability; KEEP_REHEARSAL
  now really keeps the container/image; N3 waits up to 20s instead of 3s
- docs/phase-3-evidence.md: decision recorded, new measured output

DoD: 1, 3 (as amended by Sam), 4, 8 met with recorded output. 2, 5, 6 deferred
on the Phase 2 binary; 7 is Sam's Caddy apply. rehearse.sh 24/24, exit 0.
This commit is contained in:
System agent
2026-10-26 17:44:22 +11:00
parent 8b3209fab5
commit e6240c1e8e
5 changed files with 147 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
deploy/README.md
View File

@@ -8,7 +8,7 @@ host: change these files in git and deploy again.
|---|---|
| `deploy.sh` | build + test → release → flip → `up -d` → health gate → rollback on failure |
| `deploy.sh --rollback` | restore the previous release in one command |
| `docker-compose.yml` | runtime container: `127.0.0.1:8096`, `mem_limit == memswap_limit == 120m`, capped logs |
| `docker-compose.yml` | runtime container: published on `127.0.0.1:8096` **and** `192.168.20.13:8096` (never `0.0.0.0`), `mem_limit == memswap_limit == 120m`, capped logs |
| `Dockerfile` | runtime image only — alpine + the prebuilt release payload, no toolchain, no network |
| `rehearse.sh` | repeatable proof that deploy, fail-fast, health-gate rollback and `--rollback` all work |
@@ -67,7 +67,8 @@ the script works on a host where `go` is not on `PATH`.
It builds three throwaway services in a scratch directory, runs the real script
against the real release root and the real port, and asserts:
1. a good release deploys, answers `/healthz`, publishes on `127.0.0.1` only,
1. a good release deploys, answers `/healthz` over loopback and the LAN
address, publishes on exactly those two addresses with no wildcard bind,
and has `memswap_limit == mem_limit`;
2. a build failure exits non-zero, leaves `current` untouched and keeps serving;
3. a release whose `/healthz` is `500` is rolled back by the health gate, exits
@@ -85,9 +86,26 @@ host swap on a host that is already swapping. Measured RSS for a Go static
server is single-digit MiB; `deploy.sh` prints the real figure after every
deploy so drift shows up in the log.
## Bind addresses — decided 2026-10-26
The container publishes on two explicit addresses and nothing else:
| Address | Why |
|---|---|
| `127.0.0.1:8096` | `deploy.sh`'s health gate and any check made on `.13` itself |
| `192.168.20.13:8096` | the LAN address Caddy on `.35` proxies to (`docs/phase-3-deploy.md` §3.3) |
A wildcard bind (`0.0.0.0`) is still forbidden: Caddy on `.35` stays the only
public listener. The phase document asked for loopback only, but a loopback-only
listener is unreachable from `.35`; Sam resolved the contradiction on AUD-133
with "A - dual bind: 127.0.0.1:8096 and 192.168.20.13:8096". `APP_LAN_IP`
overrides the LAN address (default `192.168.20.13`); `deploy.sh --lan-ip ADDR`
sets it for one run. Both `deploy.sh` and `rehearse.sh` assert that the LAN
address answers, not just loopback.
## Caddy
`docs/phase-3-deploy.md` §3.3 holds the block for `.35`. It is additive, applied
with `caddy reload` (never a restart), and **Sam applies it** — see
`docs/phase-3-evidence.md` for the open bind-address question that decides
whether that block points at `192.168.20.13:8096` or at `.13`'s Caddy.
with `caddy reload` (never a restart), and **Sam applies it**. The block proxies
to `192.168.20.13:8096`, which is why the container publishes on that address as
well as loopback (see *Bind addresses* above).

20
deploy/deploy.sh
View File

@@ -28,6 +28,10 @@ DEFAULT_ROOT="/home/sam/deployment/resume"
SRC_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
ROOT="${DEPLOY_ROOT:-$DEFAULT_ROOT}"
PORT="${APP_PORT:-$DEFAULT_PORT}"
# Caddy on .35 proxies to this host's LAN address (phase doc §3.3), so the
# container publishes on loopback *and* on that address. Sam's decision on
# AUD-133, 2026-10-26: "A - dual bind: 127.0.0.1:8096 and 192.168.20.13:8096".
LAN_IP="${APP_LAN_IP:-192.168.20.13}"
DO_ROLLBACK=0
HEALTH_TIMEOUT="${HEALTH_TIMEOUT:-40}"
@@ -39,6 +43,7 @@ Usage: deploy.sh [options]
--source DIR build from DIR instead of the repo this script lives in
--root DIR release root (default /home/sam/deployment/resume)
--port N app port (default 8096)
--lan-ip ADDR LAN address the container also publishes on (default 192.168.20.13)
--health-timeout N seconds to wait for /healthz (default 40)
-h, --help this text
@@ -46,6 +51,7 @@ Environment:
GO path to the go toolchain (auto-detected, incl. /nix/store)
DEPLOY_ROOT same as --root
APP_PORT same as --port
APP_LAN_IP same as --lan-ip
EOF
}
@@ -55,6 +61,7 @@ while [[ $# -gt 0 ]]; do
--source) SRC_DIR="$(cd "$2" && pwd)"; shift 2 ;;
--root) ROOT="$2"; shift 2 ;;
--port) PORT="$2"; shift 2 ;;
--lan-ip) LAN_IP="$2"; shift 2 ;;
--health-timeout) HEALTH_TIMEOUT="$2"; shift 2 ;;
-h|--help) usage; exit 0 ;;
*) echo "unknown argument: $1" >&2; usage >&2; exit 2 ;;
@@ -110,6 +117,17 @@ check_health() {
fi
fi
log "health: $url -> 200"
# The container also publishes on the LAN address because that is what Caddy
# on .35 proxies to. A loopback-only success would be a site nobody can reach.
local lan_url lan_code
lan_url="http://${LAN_IP}:${PORT}/healthz"
lan_code=$(curl -s --max-time 3 -o /dev/null -w '%{http_code}' "$lan_url" 2>/dev/null || true)
if [[ "$lan_code" != "200" ]]; then
log "health: $lan_url -> HTTP ${lan_code:-none} (LAN bind missing?)"
return 1
fi
log "health: $lan_url -> 200"
return 0
}
@@ -218,7 +236,7 @@ do_deploy() {
echo "built_on=$(hostname)"
echo "binary_sha256=$(sha256sum "$release/bin/server" | cut -d' ' -f1)"
} > "$release/manifest.txt"
printf 'APP_VERSION=%s\nAPP_PORT=%s\n' "$ts" "$PORT" > "$release/.env"
printf 'APP_VERSION=%s\nAPP_PORT=%s\nAPP_LAN_IP=%s\n' "$ts" "$PORT" "$LAN_IP" > "$release/.env"
# 3. Runtime image, tagged with this release.
log "deploy: docker build resume/app:$ts"

10
deploy/docker-compose.yml
View File

@@ -6,7 +6,14 @@
#
# Limits that are not negotiable (AGENTS.md §4.3):
# mem_limit == memswap_limit == 120m -> the container cannot touch host swap
# ports 127.0.0.1:$PORT:8096 -> Caddy on .35 is the only public listener
# ports never 0.0.0.0 -> Caddy on .35 is the only public listener
#
# Published on two explicit addresses and nothing else (Sam, 2026-10-26, on
# AUD-133: "A - dual bind: 127.0.0.1:8096 and 192.168.20.13:8096"):
# 127.0.0.1 -> deploy.sh health gate and local checks on .13
# 192.168.20.13 -> the LAN address Caddy on .35 proxies to (phase doc §3.3)
# A wildcard bind is still forbidden; if APP_LAN_IP is unset the LAN address
# defaults to this host's own 192.168.20.13.
#
# .13 has every default Docker address pool subnetted out (many projects), so a
# single-container service uses the host bridge and publishes its port rather
@@ -22,6 +29,7 @@ services:
network_mode: bridge
ports:
- "127.0.0.1:${APP_PORT:-8096}:8096"
- "${APP_LAN_IP:-192.168.20.13}:${APP_PORT:-8096}:8096"
environment:
PORT: "8096"
APP_VERSION: "${APP_VERSION}"

36
deploy/rehearse.sh
View File

@@ -4,7 +4,7 @@
# Builds three throwaway Go services in a scratch directory and runs the real
# deploy mechanism against the real release root and the real port:
#
# 1. good -> deploys, health-gated, serving
# 1. good -> deploys, health-gated, serving on loopback and the LAN address
# 2. broken -> does not compile: deploy must fail fast, current must not move
# 3. unhealthy -> builds and runs, but /healthz is 500: the health gate must
# roll back to the previous release and exit non-zero
@@ -24,6 +24,7 @@ HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DEPLOY="$HERE/deploy.sh"
ROOT="${DEPLOY_ROOT:-/home/sam/deployment/resume}"
PORT="${APP_PORT:-8096}"
LAN_IP="${APP_LAN_IP:-192.168.20.13}"
SCRATCH="${REHEARSAL_DIR:-$(mktemp -d -t resume-rehearsal-XXXXXX)}"
KEEP="${KEEP_REHEARSAL:-0}"
@@ -33,19 +34,19 @@ no() { printf ' FAIL %s\n' "$*"; fail=$((fail + 1)); }
hdr() { printf '\n== %s\n' "$*"; }
cleanup() {
if [[ "$KEEP" == "1" ]]; then
printf '\nkept for inspection: container resume-app, images resume/app:*, release root %s, scratch %s\n' "$ROOT" "$SCRATCH"
return 0
fi
if docker ps -a --format '{{.Names}}' | grep -qx 'resume-app'; then
docker rm -f resume-app >/dev/null 2>&1 || true
fi
docker images --format '{{.Repository}}:{{.Tag}}' | grep -q '^resume/app:' \
&& docker images --format '{{.Repository}}:{{.Tag}}' | grep '^resume/app:' \
| xargs -r docker rmi -f >/dev/null 2>&1 || true
if [[ "$KEEP" == "1" ]]; then
printf '\nkept: release root %s, scratch %s, images resume/app:*\n' "$ROOT" "$SCRATCH"
else
rm -rf "$ROOT"
[[ "$SCRATCH" == /tmp/resume-rehearsal-* || -n "${REHEARSAL_DIR:-}" ]] && rm -rf "$SCRATCH"
printf '\ncleaned: release root and rehearsal sources removed\n'
fi
rm -rf "$ROOT"
[[ "$SCRATCH" == /tmp/resume-rehearsal-* || -n "${REHEARSAL_DIR:-}" ]] && rm -rf "$SCRATCH"
printf '\ncleaned: container, images, release root and rehearsal sources removed\n'
}
trap cleanup EXIT
@@ -111,6 +112,8 @@ PY
}
health() { curl -s -m 3 -o /dev/null -w '%{http_code}' "http://127.0.0.1:$PORT/healthz" || true; }
health_lan() { curl -s -m 3 -o /dev/null -w '%{http_code}' "http://$LAN_IP:$PORT/healthz" || true; }
listeners() { ss -ltn 2>/dev/null | awk -v p=":${PORT}\$" '$4 ~ p {print $4}' | sort -u; }
serving_version() { curl -s -m 3 "http://127.0.0.1:$PORT/healthz" | sed -n 's/.*"version":"\([^"]*\)".*/\1/p'; }
current_target() { [[ -L "$ROOT/current" ]] && readlink -f "$ROOT/current" || echo none; }
@@ -136,7 +139,14 @@ else
fi
[[ "$(health)" == "200" ]] && ok "/healthz 200 on 127.0.0.1:$PORT" || no "/healthz not 200"
v1=$(serving_version); [[ -n "$v1" ]] && ok "serving release $v1" || no "no version reported"
ss -ltn | grep -q "127.0.0.1:$PORT" && ok "container publishes on 127.0.0.1 only" || no "unexpected bind"
ss -ltn | grep -q "127.0.0.1:$PORT" && ok "container publishes on 127.0.0.1:$PORT (loopback, used by the deploy.sh health gate)" || no "no loopback bind"
ss -ltn | grep -q "$LAN_IP:$PORT" && ok "container publishes on $LAN_IP:$PORT (the address Caddy on .35 proxies to)" || no "no LAN bind on $LAN_IP:$PORT"
if listeners | grep -qE '^(0\.0\.0\.0|\*|\[::\]|::)'; then
no "wildcard bind on $PORT: $(listeners | tr '\n' ' ')"
else
ok "no wildcard bind on $PORT — only: $(listeners | tr '\n' ' ')"
fi
[[ "$(health_lan)" == "200" ]] && ok "/healthz 200 over the LAN address http://$LAN_IP:$PORT" || no "LAN address not answering"
mem=$(docker inspect -f '{{.HostConfig.Memory}}' resume-app); swp=$(docker inspect -f '{{.HostConfig.MemorySwap}}' resume-app)
[[ "$mem" == "$swp" && "$mem" != "0" ]] && ok "memswap_limit == mem_limit ($mem bytes)" || no "mem limits differ ($mem vs $swp)"
@@ -175,8 +185,12 @@ rel=$(readlink -f "$ROOT/current")
docker compose -p resume --project-directory "$rel" -f "$rel/docker-compose.yml" down >/dev/null 2>&1
[[ "$(health)" != "200" ]] && ok "service down after compose down" || no "still serving after compose down"
docker compose -p resume --project-directory "$rel" -f "$rel/docker-compose.yml" up -d >/dev/null 2>&1
sleep 3
[[ "$(health)" == "200" ]] && ok "service restored after compose up" || no "service did not come back"
restored=0
for _ in $(seq 1 20); do
if [[ "$(health)" == "200" ]]; then restored=1; break; fi
sleep 1
done
[[ $restored == 1 ]] && ok "service restored after compose up" || no "service did not come back within 20s"
# --------------------------------------------------------------- verdict
hdr "verdict"