.gitea/workflows/check.yml

@@ -7,3 +7,4 @@ jobs:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
             - run: script/cibuild
+            - run: script/docker-smoke

Dockerfile

@@ -76,4 +76,7 @@ WORKDIR /var/lib/pixa
 
 EXPOSE 8080
 
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD wget --spider -q http://localhost:8080/.well-known/healthcheck.json || exit 1
+
 ENTRYPOINT ["/usr/local/bin/pixad", "--config", "/etc/pixa/config.yml"]

Makefile

@@ -1,4 +1,4 @@
-.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker docker-versioned docker-test devserver devserver-stop hooks
+.PHONY: bootstrap setup check lint test fmt fmt-check build clean docker docker-smoke docker-versioned docker-test devserver devserver-stop hooks
 
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 LDFLAGS := -X main.Version=$(VERSION)
@@ -54,6 +54,11 @@ clean:
 docker:
 	@script/docker
 
+# Build the image, start it, and wait for its healthcheck (needs Docker;
+# not part of check)
+docker-smoke:
+	@script/docker-smoke
+
 # Build Docker image tagged pixad:$(VERSION) and pixad:latest
 docker-versioned:
 	docker build --build-arg VERSION=$(VERSION) -t pixad:$(VERSION) -t pixad:latest .

README.md

@@ -176,6 +176,7 @@ them. We provide:
 - `script/fmt-check` — check formatting (read-only)
 - `script/check` — run test, lint, and fmt-check
 - `script/docker` — build the Docker image tagged via `script/projectname`
+- `script/docker-smoke` — build the image, start it, wait for it to be healthy
 - `script/cibuild` — CI entrypoint: `docker build .` (the Dockerfile
   runs the checks, so a green build implies a green repo)
 - `script/precommit` — pre-commit checks (`go mod tidy` guard, then

TODO.md

@@ -30,6 +30,12 @@ exhaustion
 
 # Completed Steps
 
+- 2026-09-28 Docker image healthcheck (closes #111): a `HEALTHCHECK` in
+  the runtime stage probing `/.well-known/healthcheck.json` with busybox
+  `wget`; `script/docker-smoke` (`make docker-smoke`) builds the image,
+  starts it with a throwaway `PIXA_SIGNING_KEY`, and passes only once
+  Docker reports it healthy within 30 seconds, removing the container on
+  exit; the Gitea workflow runs it after `script/cibuild`.
 - 2026-09-21 trusted-proxy client IP resolution (closes #94): a
   `trusted_proxies` config key taking a list of CIDRs, parsed by the same
   `net/netip` list parser as `blocked_networks` (an invalid entry aborts

script/docker-smoke

@@ -0,0 +1,44 @@
+#!/bin/sh
+# script/docker-smoke: build the Docker image, start it, and wait up to
+# 30 seconds for its HEALTHCHECK to report healthy. Needs a Docker
+# daemon, so it is not part of script/check; the Gitea workflow runs it
+# after script/cibuild.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    "$SCRIPT_DIR/docker"
+
+    # A fresh random key: the container publishes no port and is
+    # removed on exit.
+    key="$(head -c 32 /dev/urandom | base64)"
+
+    # --health-interval=1s overrides the image's 30s interval so the
+    # first probe does not use up the whole wait.
+    cid="$(docker create --health-interval=1s \
+        -e PIXA_SIGNING_KEY="$key" "$("$SCRIPT_DIR/projectname")")"
+    # Remove the container on any exit; turning signals into exit makes
+    # an interrupted run clean up too.
+    trap 'docker rm -f "$cid" >/dev/null' EXIT
+    trap 'exit 1' HUP INT TERM
+    docker start "$cid" >/dev/null
+
+    deadline=$(($(date +%s) + 30))
+    while [ "$(date +%s)" -lt "$deadline" ]; do
+        health="$(docker inspect --format '{{.State.Health.Status}}' "$cid")"
+        if [ "$health" = healthy ]; then
+            echo "docker-smoke: container is healthy"
+            return 0
+        fi
+        sleep 1
+    done
+
+    echo "docker-smoke: container not healthy after 30 seconds; its log:" >&2
+    docker logs "$cid" >&2
+    return 1
+}
+
+main "$@"