From 9d0462a2a668f41ed2bc072fa58a2eaef2586c57 Mon Sep 17 00:00:00 2001
From: clawbot <35+clawbot@noreply.example.org>
Date: Mon, 28 Sep 2026 23:51:57 +0000
Subject: [PATCH] build: one image, nginx in front of the backend on loopback
 (closes #52)

The root Dockerfile builds the only image; Dockerfile.backend is gone.
Its stages: lint, a Go stage that runs the tests and builds
netwatch-server, the node stage, and an nginx runtime. nginx serves
dist/ on 8080 and proxies /api/ and /.well-known/healthcheck to the
backend on 127.0.0.1:8081. bin/entrypoint.sh starts both, turns TERM or
INT into a stop of both, and exits non-zero when either exits on its
own. The backend runs as user netwatch and keeps reports on the /data
volume. New setting BIND_ADDRESS (empty: every interface). STOPSIGNAL is
SIGTERM, since the nginx image's SIGQUIT would miss the entrypoint.
script/docker is the org model verbatim.

Model: opus-5-5
---
 .gitea/workflows/check.yml             |  2 +-
 Dockerfile                             | 73 ++++++++++++++++++++++++--
 Dockerfile.backend                     | 49 -----------------
 README.md                              | 20 ++++---
 TODO.md                                |  8 +++
 backend/Makefile                       |  2 +-
 backend/README.md                      | 25 ++++++---
 backend/internal/config/config.go      |  4 ++
 backend/internal/server/export_test.go |  6 +++
 backend/internal/server/http.go        |  8 ++-
 backend/internal/server/http_test.go   | 32 +++++++++++
 backend/internal/server/routes_test.go | 22 +++++---
 backend/script/build                   |  2 +-
 backend/script/lint                    |  2 +-
 bin/entrypoint.sh                      | 59 +++++++++++++++++++++
 nginx.conf                             | 19 +++++++
 script/bootstrap                       |  4 +-
 script/cibuild                         | 10 ++--
 script/docker                          | 20 ++++---
 script/frontend-check                  |  8 +--
 script/lint                            |  6 +--
 21 files changed, 280 insertions(+), 101 deletions(-)
 delete mode 100644 Dockerfile.backend
 create mode 100644 backend/internal/server/http_test.go
 create mode 100755 bin/entrypoint.sh

diff --git a/.gitea/workflows/check.yml b/.gitea/workflows/check.yml
index a732557..06b80af 100644
--- a/.gitea/workflows/check.yml
+++ b/.gitea/workflows/check.yml
@@ -6,5 +6,5 @@ jobs:
         steps:
             # actions/checkout v4.2.2, 2026-02-22
             - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-            # script/cibuild builds both images.
+            # script/cibuild builds the image, whose stages run every check.
             - run: script/cibuild
diff --git a/Dockerfile b/Dockerfile
index 492b41d..3e13950 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,5 +1,51 @@
+# The one image netwatch ships: nginx serves the built frontend and
+# passes /api/ and /.well-known/healthcheck to netwatch-server, the Go
+# backend, which runs in the same container on loopback only.
+# bin/entrypoint.sh starts and watches both.
+
+# Lint stage — fast feedback on formatting and lint issues. The
+# golangci/golangci-lint image ships Go, gofmt, make and the linter, so
+# nothing is installed here. The root make lint builds this stage alone.
+# golangci/golangci-lint:v2.12.2 (2026-08-10)
+FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
+
+WORKDIR /src
+COPY backend/go.mod backend/go.sum ./
+RUN go mod download
+COPY backend/ .
+RUN make fmt-check
+RUN make lint
+
+# Backend build stage
+# golang:1.25-alpine (2026-02-27)
+FROM golang:1.25-alpine@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
+
+RUN apk add --no-cache make
+
+WORKDIR /src
+
+# Force BuildKit to run the lint stage before proceeding. BuildKit runs
+# stages in parallel by default; without this no-op copy a lint failure
+# would not gate compilation.
+COPY --from=lint /src/go.sum /dev/null
+
+COPY backend/go.mod backend/go.sum ./
+RUN go mod download
+COPY backend/ .
+
+RUN make test
+
+# make build is a shim around backend/script/build, the one definition
+# of the build command:
+# CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.Version=... -X main.Buildarch=..."
+# That script reads VERSION from the environment, so it is handed over
+# there rather than as a make variable.
+ARG VERSION=dev
+RUN VERSION="${VERSION}" make build
+
+# Frontend stage
 # node:22-alpine as of 2026-02-22
-FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS build
+FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34 AS frontend
 WORKDIR /app
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile
@@ -8,16 +54,33 @@ COPY . .
 # make frontend-check is the frontend half of make check (test + lint +
 # fmt-check); its test step is the production yarn build, so this both
 # produces dist/ and gates the image on lint/fmt-check/test regressions.
-# This node stage has neither Go nor Docker for the other half, which
-# Dockerfile.backend gates; script/cibuild builds both images.
+# This node stage has neither Go nor Docker; the lint and builder stages
+# above gate the backend half.
 RUN make frontend-check
 
+# Runtime stage
 # nginx:stable-alpine as of 2026-02-22
 FROM nginx@sha256:15e96e59aa3b0aada3a121296e3bce117721f42d88f5f64217ef4b18f458c6ab
+
+# netwatch-server runs as this user, which owns the report directory.
+# nginx keeps the image's own arrangement: master process as root,
+# workers as the nginx user.
+RUN addgroup -g 1000 -S netwatch && \
+    adduser -u 1000 -S netwatch -G netwatch
+
 RUN rm /etc/nginx/conf.d/default.conf
 COPY nginx.conf /etc/nginx/conf.d/netwatch.conf
-COPY --from=build /app/dist /usr/share/nginx/html
+COPY --from=frontend /app/dist /usr/share/nginx/html
+COPY --from=builder /src/netwatch-server /usr/local/bin/netwatch-server
+COPY bin/entrypoint.sh /usr/local/bin/entrypoint.sh
+
+ENV DATA_DIR=/data/reports
+RUN mkdir -p /data/reports && chown -R netwatch:netwatch /data
+VOLUME /data
 
 EXPOSE 8080
 
-CMD ["nginx", "-g", "daemon off;"]
+# The nginx image stops its container with SIGQUIT; the entrypoint
+# acts on TERM and INT.
+STOPSIGNAL SIGTERM
+ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
diff --git a/Dockerfile.backend b/Dockerfile.backend
deleted file mode 100644
index 51a530f..0000000
--- a/Dockerfile.backend
+++ /dev/null
@@ -1,49 +0,0 @@
-# Lint stage — fast feedback on formatting and lint issues. The
-# golangci/golangci-lint image ships Go, gofmt, make and the linter, so
-# nothing is installed here.
-# golangci/golangci-lint:v2.12.2 (2026-08-10)
-FROM golangci/golangci-lint@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS lint
-
-WORKDIR /src
-COPY backend/go.mod backend/go.sum ./
-RUN go mod download
-COPY backend/ .
-RUN make fmt-check
-RUN make lint
-
-# Build stage
-# golang:1.25-alpine (2026-02-27)
-FROM golang:1.25-alpine@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4ced AS builder
-
-RUN apk add --no-cache make
-
-WORKDIR /src
-
-# Force BuildKit to run the lint stage before proceeding. BuildKit runs
-# stages in parallel by default; without this no-op copy a lint failure
-# would not gate compilation.
-COPY --from=lint /src/go.sum /dev/null
-
-COPY backend/go.mod backend/go.sum ./
-RUN go mod download
-COPY backend/ .
-
-RUN make test
-
-# make build is a shim around backend/script/build, the one definition
-# of the build command:
-# CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.Version=... -X main.Buildarch=..."
-# That script reads VERSION from the environment, so it is handed over
-# there rather than as a make variable.
-ARG VERSION=dev
-RUN VERSION="${VERSION}" make build
-
-# Runtime stage
-# alpine:3.23 (2026-02-27)
-FROM alpine:3.23@sha256:25109184c71bdad752c8312a8623239686a9a2071e8825f20acb8f2198c3f659
-
-RUN apk add --no-cache ca-certificates
-COPY --from=builder /src/netwatch-server /usr/local/bin/netwatch-server
-
-EXPOSE 8080
-ENTRYPOINT ["netwatch-server"]
diff --git a/README.md b/README.md
index 52e6382..aa90734 100644
--- a/README.md
+++ b/README.md
@@ -44,11 +44,11 @@ halves, so the root `make check` fails if either one is broken. We provide:
   linter in Docker
 - `script/setup` — make a fresh clone ready for development: bootstrap plus the
   git pre-commit hook
-- `script/projectname` — print the project name (used for the Docker image tags)
+- `script/projectname` — print the project name (used for the Docker image tag)
 - `script/test` — run `script/frontend-test`, then the backend's Go tests, both
   within one 30-second timeout
 - `script/lint` — run `script/frontend-lint`, then golangci-lint in Docker, by
-  building the lint stage of `Dockerfile.backend` without the cache
+  building the lint stage of `Dockerfile` without the cache
 - `script/fmt` — format all files (writes): prettier, then gofmt over `backend/`
 - `script/fmt-check` — check formatting (read-only): prettier, then gofmt
 - `script/check` — run test, lint, and fmt-check
@@ -63,9 +63,9 @@ halves, so the root `make check` fails if either one is broken. We provide:
   frontend in a containerised headless Chrome (see
   [test/viewport/README.md](test/viewport/README.md)). Not part of
   `script/check`: it needs Docker and takes minutes.
-- `script/docker` — build both images, tagged via `script/projectname`:
-  `netwatch` from `Dockerfile` and `netwatch-server` from `Dockerfile.backend`
-- `script/cibuild` — CI entrypoint: builds both images
+- `script/docker` — build the image from `Dockerfile` without the build cache,
+  tagged `netwatch` via `script/projectname`
+- `script/cibuild` — CI entrypoint: builds the image
 - `script/precommit` — run by the git pre-commit hook; runs `script/check`
 - `script/install-precommit` — install the git pre-commit hook
 
@@ -178,13 +178,21 @@ After running `yarn build`, deploy the contents of the `dist/` directory to any
 static file host (S3, GCS, Cloudflare Pages, Vercel, Netlify, GitHub Pages) or
 use the Docker image behind a reverse proxy.
 
-The Docker image:
+The Docker image, built from `Dockerfile`, is the whole service in one
+container: nginx serves the built frontend and passes `/api/` and
+`/.well-known/healthcheck` to the Go backend, `netwatch-server`, which listens
+only inside the container, on `127.0.0.1:8081`. The image:
 
 - Listens on port 8080 by default (override with `PORT` env var)
 - Trusts `X-Forwarded-For` from RFC1918 reverse proxies (10/8, 172.16/12,
   192.168/16)
 - Sends access logs to stdout
 - Caches static assets with immutable headers
+- Stores reports in `DATA_DIR`, `/data/reports` by default, on the `/data`
+  volume. The backend runs as user `netwatch` (uid 1000), so a directory
+  bind-mounted at `/data` must be writable by uid 1000
+- Writes buffered reports to disk on `docker stop`, and exits non-zero if nginx
+  or the backend exits on its own, so the platform restarts it
 
 ## Browser Compatibility
 
diff --git a/TODO.md b/TODO.md
index ecb3301..f96341a 100644
--- a/TODO.md
+++ b/TODO.md
@@ -23,6 +23,14 @@ latest run passes.
 
 # Completed Steps
 
+- 2026-09-28: one container image (issue #52): the root `Dockerfile` builds the
+  only image, and `Dockerfile.backend` is gone. nginx serves the frontend on
+  port 8080 and proxies `/api/` and `/.well-known/healthcheck` to the backend,
+  which listens on `127.0.0.1:8081` in the same container; the new
+  `BIND_ADDRESS` setting sets its listen address. `bin/entrypoint.sh` starts
+  both, passes TERM and INT on to both, and exits non-zero when either exits on
+  its own. The backend runs as user `netwatch` and stores reports on the `/data`
+  volume. `script/docker` is the org model again
 - 2026-09-28: unified the gate (issue #16): the root `make check` covers the Go
   backend as well as the frontend, and the pre-commit hook with it; the backend
   moved onto scripts-to-rule-them-all (`backend/script/*`, `backend/Makefile` as
diff --git a/backend/Makefile b/backend/Makefile
index 5724459..faf9ec5 100644
--- a/backend/Makefile
+++ b/backend/Makefile
@@ -2,7 +2,7 @@
 # Entrypoints section of README.md). There is no check, hooks or docker
 # target here: the root Makefile's check covers this directory, its
 # hooks target installs the repo's only pre-commit hook, and its docker
-# target builds this image, whose build context is the repo root.
+# target builds the one image, which contains this backend.
 
 .PHONY: all build test lint fmt fmt-check run clean
 
diff --git a/backend/README.md b/backend/README.md
index 1230c12..fa4af1b 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -11,15 +11,16 @@ From this directory:
 make run
 ```
 
-From the repo root, which is also the build context of `Dockerfile.backend`:
+From the repo root, whose `Dockerfile` builds the one image that ships this
+backend behind nginx (see [Container image](#container-image)):
 
 ```bash
 # Run tests, lint, and format check over the frontend and this backend
 make check
 
-# Build both images, including netwatch-server
+# Build the image: nginx, the frontend and this backend
 make docker
-docker run -p 8080:8080 netwatch-server
+docker run -p 8080:8080 netwatch
 ```
 
 ## Entrypoints
@@ -27,7 +28,7 @@ docker run -p 8080:8080 netwatch-server
 This directory follows the same
 [Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
 pattern as the repo root: the targets in `backend/Makefile` are thin shims over
-`backend/script/`. `Dockerfile.backend` runs them, and the root scripts call
+`backend/script/`. The root `Dockerfile` runs them, and the root scripts call
 `test`, `fmt` and `fmt-check`:
 
 - `script/build` — compile the static `netwatch-server` binary with its version
@@ -37,8 +38,8 @@ pattern as the repo root: the targets in `backend/Makefile` are thin shims over
 - `script/test` — run the Go tests under a 30-second timeout
 - `script/lint` — check `.golangci.yml` against its pinned sha256, then run
   golangci-lint. It runs inside the golangci-lint image of the lint stage of
-  `Dockerfile.backend`; from a checkout, run `make lint` at the repo root, which
-  builds that stage
+  the root `Dockerfile`; from a checkout, run `make lint` at the repo root,
+  which builds that stage
 - `script/fmt` — format the Go sources (writes)
 - `script/fmt-check` — check Go formatting (read-only)
 - `script/run` — build and run the server locally
@@ -46,7 +47,7 @@ pattern as the repo root: the targets in `backend/Makefile` are thin shims over
 
 There is no `check`, `hooks` or `docker` target here: the root `make check`
 covers this directory, the root `make hooks` installs the repo's only pre-commit
-hook, and the root `make docker` builds this image.
+hook, and the root `make docker` builds the image that contains this backend.
 
 ## Rationale
 
@@ -76,6 +77,7 @@ Internal packages in `internal/` follow standard Go project layout:
 
 | Variable          | Default              | Description                                                                                              |
 | ----------------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `BIND_ADDRESS`    | empty                | IP address to listen on; empty listens on every interface                                                |
 | `PORT`            | `8080`               | HTTP listen port                                                                                         |
 | `DATA_DIR`        | `./data/reports`     | Directory for compressed reports                                                                         |
 | `DEBUG`           | `false`              | Enable debug logging                                                                                     |
@@ -86,6 +88,15 @@ The loopback entries cover the reverse proxy that shares the container; the
 RFC1918 ranges match `nginx.conf`. A request whose direct peer is outside this
 set has its forwarded headers ignored, and the direct peer is logged instead.
 
+### Container image
+
+The root `Dockerfile` builds one image in which nginx listens on the public port
+8080, serves the frontend, and proxies `/api/` and `/.well-known/healthcheck` to
+this server. The image's entrypoint, `bin/entrypoint.sh`, starts the server as
+user `netwatch` (uid 1000) with `BIND_ADDRESS=127.0.0.1` and `PORT=8081`, so
+only nginx reaches it. `DATA_DIR` is `/data/reports`, on the `/data` volume,
+which `netwatch` owns.
+
 ### Report storage
 
 Reports are written as `reports-<timestamp>.jsonl.zst` files in `DATA_DIR`.
diff --git a/backend/internal/config/config.go b/backend/internal/config/config.go
index 02a6db9..4f60de4 100644
--- a/backend/internal/config/config.go
+++ b/backend/internal/config/config.go
@@ -33,6 +33,7 @@ type Params struct {
 
 // Config holds the resolved application configuration.
 type Config struct {
+	BindAddress     string
 	DataDir         string
 	Debug           bool
 	MetricsPassword string
@@ -62,6 +63,8 @@ func New(
 
 	viper.SetDefault("DATA_DIR", "./data/reports")
 	viper.SetDefault("DEBUG", "false")
+	// An empty BIND_ADDRESS listens on every interface.
+	viper.SetDefault("BIND_ADDRESS", "")
 	viper.SetDefault("PORT", "8080")
 	viper.SetDefault("SENTRY_DSN", "")
 	viper.SetDefault("METRICS_USERNAME", "")
@@ -78,6 +81,7 @@ func New(
 	}
 
 	s := &Config{
+		BindAddress:     viper.GetString("BIND_ADDRESS"),
 		DataDir:         viper.GetString("DATA_DIR"),
 		Debug:           viper.GetBool("DEBUG"),
 		MetricsPassword: viper.GetString("METRICS_PASSWORD"),
diff --git a/backend/internal/server/export_test.go b/backend/internal/server/export_test.go
index 7279b22..84cdd90 100644
--- a/backend/internal/server/export_test.go
+++ b/backend/internal/server/export_test.go
@@ -3,3 +3,9 @@ package server
 // MaxRequestBodyBytes exposes the router-wide body limit to the
 // external tests.
 const MaxRequestBodyBytes = maxRequestBodyBytes
+
+// ListenAddr exposes the address the server listens on to the
+// external tests.
+func (s *Server) ListenAddr() string {
+	return s.newHTTPServer().Addr
+}
diff --git a/backend/internal/server/http.go b/backend/internal/server/http.go
index e621ce7..46f4a67 100644
--- a/backend/internal/server/http.go
+++ b/backend/internal/server/http.go
@@ -2,8 +2,9 @@ package server
 
 import (
 	"errors"
-	"fmt"
+	"net"
 	"net/http"
+	"strconv"
 	"time"
 
 	"go.uber.org/fx"
@@ -27,7 +28,10 @@ const (
 // newHTTPServer constructs the http.Server. It performs no I/O
 // and does not start listening.
 func (s *Server) newHTTPServer() *http.Server {
-	listenAddr := fmt.Sprintf(":%d", s.params.Config.Port)
+	listenAddr := net.JoinHostPort(
+		s.params.Config.BindAddress,
+		strconv.Itoa(s.params.Config.Port),
+	)
 
 	return &http.Server{
 		Addr:              listenAddr,
diff --git a/backend/internal/server/http_test.go b/backend/internal/server/http_test.go
new file mode 100644
index 0000000..d1370df
--- /dev/null
+++ b/backend/internal/server/http_test.go
@@ -0,0 +1,32 @@
+package server_test
+
+import "testing"
+
+// TestListenAddress checks that the server listens on BIND_ADDRESS
+// and PORT, and on port 8080 on every interface when neither is set.
+// The container image sets both, to keep the backend on loopback
+// behind nginx.
+func TestListenAddress(t *testing.T) {
+	tests := []struct {
+		bindAddress string
+		port        string
+		want        string
+	}{
+		{bindAddress: "", port: "", want: ":8080"},
+		{bindAddress: "127.0.0.1", port: "8081", want: "127.0.0.1:8081"},
+		{bindAddress: "::1", port: "8081", want: "[::1]:8081"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.want, func(t *testing.T) {
+			// t.Setenv rules out t.Parallel.
+			t.Setenv("BIND_ADDRESS", tt.bindAddress)
+			t.Setenv("PORT", tt.port)
+
+			got := newServer(t).ListenAddr()
+			if got != tt.want {
+				t.Errorf("listen address = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
diff --git a/backend/internal/server/routes_test.go b/backend/internal/server/routes_test.go
index 1a50a7f..71f5117 100644
--- a/backend/internal/server/routes_test.go
+++ b/backend/internal/server/routes_test.go
@@ -19,16 +19,14 @@ import (
 	"go.uber.org/fx/fxtest"
 )
 
-// TestHealthCheckRejectsOversizeBody sends the health check, which
-// never reads its body, a body one byte over the limit. Only the
-// router-wide body limit can reject it.
-func TestHealthCheckRejectsOversizeBody(t *testing.T) {
-	t.Parallel()
+// newServer builds a Server from the same constructors as main,
+// configured from the environment. It is never started, so nothing
+// listens.
+func newServer(t *testing.T) *server.Server {
+	t.Helper()
 
 	var srv *server.Server
 
-	// The same constructors as main, never started: SetupRoutes is
-	// called directly, so nothing listens.
 	app := fxtest.New(t,
 		fx.Provide(
 			config.New,
@@ -48,6 +46,16 @@ func TestHealthCheckRejectsOversizeBody(t *testing.T) {
 		t.Fatalf("build server: %v", err)
 	}
 
+	return srv
+}
+
+// TestHealthCheckRejectsOversizeBody sends the health check, which
+// never reads its body, a body one byte over the limit. Only the
+// router-wide body limit can reject it.
+func TestHealthCheckRejectsOversizeBody(t *testing.T) {
+	t.Parallel()
+
+	srv := newServer(t)
 	srv.SetupRoutes()
 
 	rec := httptest.NewRecorder()
diff --git a/backend/script/build b/backend/script/build
index 36b3e96..40d4d01 100755
--- a/backend/script/build
+++ b/backend/script/build
@@ -8,7 +8,7 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 main() {
     cd "$ROOT"
 
-    # VERSION comes from the environment (Dockerfile.backend passes its
+    # VERSION comes from the environment (the root Dockerfile passes its
     # ARG VERSION in). Unset or empty, it is git describe, or "dev" where
     # there is no git or no repository history.
     version="${VERSION:-$(git describe --always --dirty 2>/dev/null || echo dev)}"
diff --git a/backend/script/lint b/backend/script/lint
index d00c5b0..256f805 100755
--- a/backend/script/lint
+++ b/backend/script/lint
@@ -1,6 +1,6 @@
 #!/bin/sh
 # script/lint: run golangci-lint over the backend. This runs inside the
-# lint stage of Dockerfile.backend, whose digest-pinned golangci-lint
+# lint stage of the root Dockerfile, whose digest-pinned golangci-lint
 # image provides the linter; nothing installs golangci-lint on the host.
 # From a checkout, run `make lint` at the repo root, which builds that
 # stage.
diff --git a/bin/entrypoint.sh b/bin/entrypoint.sh
new file mode 100755
index 0000000..3dece27
--- /dev/null
+++ b/bin/entrypoint.sh
@@ -0,0 +1,59 @@
+#!/bin/sh
+# The container's entrypoint: runs netwatch-server and nginx side by
+# side. TERM or INT stops both, and the container exits 0 if both exit
+# cleanly. If either exits on its own, the other is stopped too and the
+# container exits non-zero, so the platform restarts it instead of
+# leaving it half up.
+#
+# No set -e: kill and wait return non-zero here in normal operation.
+set -u
+
+# A stop signal is only noted here; the loop below acts on it.
+stop_requested=""
+trap 'stop_requested=yes' TERM INT
+
+# netwatch-server runs as the netwatch user and listens on loopback
+# only, on a port other than the public one; nginx.conf proxies to this
+# address. The netwatch user has no login shell, hence -s /bin/sh.
+# busybox su replaces itself with the command instead of staying on as
+# its parent, so $! is the server's own PID.
+BIND_ADDRESS=127.0.0.1 PORT=8081 \
+    su -s /bin/sh netwatch -c 'exec netwatch-server' &
+backend=$!
+
+# nginx starts through the nginx image's own entrypoint, which applies
+# the image's start-up configuration and then replaces itself with
+# nginx.
+/docker-entrypoint.sh nginx -g 'daemon off;' &
+nginx=$!
+
+running() {
+    kill -0 "$1" 2>/dev/null
+}
+
+# POSIX sh cannot wait for whichever of two children exits first, so
+# look once a second. The shell collects a child that has exited while
+# it runs sleep, and running() is false for that child from then on.
+while [ -z "$stop_requested" ] && running "$backend" && running "$nginx"; do
+    sleep 1
+done
+
+# Stop both, then wait until neither is left.
+kill -TERM "$backend" "$nginx" 2>/dev/null
+while running "$backend" || running "$nginx"; do
+    sleep 1
+done
+
+wait "$backend"
+backend_status=$?
+wait "$nginx"
+nginx_status=$?
+echo "entrypoint: netwatch-server exited $backend_status," \
+    "nginx exited $nginx_status"
+
+# Success is a requested stop that both processes exited cleanly from.
+if [ -n "$stop_requested" ] && [ "$backend_status" -eq 0 ] &&
+    [ "$nginx_status" -eq 0 ]; then
+    exit 0
+fi
+exit 1
diff --git a/nginx.conf b/nginx.conf
index cb176d4..65e8aaf 100644
--- a/nginx.conf
+++ b/nginx.conf
@@ -25,4 +25,23 @@ server {
         expires 1y;
         add_header Cache-Control "public, immutable";
     }
+
+    # netwatch-server, the Go backend, runs in the same container and
+    # listens on loopback only: bin/entrypoint.sh starts it on
+    # 127.0.0.1:8081. These headers go with every request passed to it.
+    # X-Forwarded-For carries only the client address, as resolved by
+    # the real IP settings above, and not the chain the request came
+    # with: the backend takes the first entry, which a client can write.
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8081;
+    }
+
+    location = /.well-known/healthcheck {
+        proxy_pass http://127.0.0.1:8081;
+    }
 }
diff --git a/script/bootstrap b/script/bootstrap
index f94201d..66e5873 100755
--- a/script/bootstrap
+++ b/script/bootstrap
@@ -27,8 +27,8 @@ NVM_VERSION="0.40.3"
 # sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
 NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
 YARN_VERSION="1.22.22"
-# The Go inside the golang:1.25-alpine image Dockerfile.backend builds
-# with, 2026-08-09. The archive hashes are in ensure_go.
+# The Go inside the golang:1.25-alpine image Dockerfile builds the
+# backend with, 2026-08-09. The archive hashes are in ensure_go.
 GO_VERSION="1.25.7"
 
 BIN_DIR="$HOME/.local/bin"
diff --git a/script/cibuild b/script/cibuild
index d3eb606..d860bf5 100755
--- a/script/cibuild
+++ b/script/cibuild
@@ -1,9 +1,8 @@
 #!/bin/sh
-# script/cibuild: run the CI build. It builds both images: the frontend
-# from Dockerfile and the backend from Dockerfile.backend. Each runs its
-# half of the checks as build steps, so a successful cibuild implies the
-# whole repo is green. This is the only build step the Gitea workflow
-# runs.
+# script/cibuild: run the CI build: build the one image from Dockerfile,
+# whose stages run the checks as build steps (the backend's fmt-check,
+# lint and tests, and the frontend's test, lint and fmt-check). This is
+# the only build step the Gitea workflow runs.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -11,7 +10,6 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 main() {
     cd "$ROOT"
     timeout 300 docker build .
-    timeout 300 docker build -f Dockerfile.backend .
 }
 
 main "$@"
diff --git a/script/docker b/script/docker
index 6476087..c4688e8 100755
--- a/script/docker
+++ b/script/docker
@@ -1,7 +1,8 @@
 #!/bin/sh
-# script/docker: build both Docker images, tagged with the project name
-# from script/projectname: the frontend as <name>, from Dockerfile, and
-# the backend as <name>-server, from Dockerfile.backend.
+# script/docker: build the Docker image tagged with the project name.
+# Identical in all repos; the tag comes from script/projectname.
+# --no-cache because the gate phases the final stage depends on are RUN
+# steps, and a cached one is a check that did not run.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
@@ -9,9 +10,16 @@ ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    name="$("$SCRIPT_DIR/projectname")"
-    timeout 300 docker build -t "$name" .
-    timeout 300 docker build -t "$name-server" -f Dockerfile.backend .
+    # Own line: a failing command substitution inside an argument does
+    # not trip `set -e`, so the inline form degrades silently to an
+    # empty constant. VERSION is computed here because .dockerignore
+    # excludes .git, so `git describe` in a build stage yields an empty
+    # version without failing.
+    version="$(git describe --tags --always --dirty 2>/dev/null || true)"
+    [ -n "$version" ] || version="unknown"
+    docker build --no-cache \
+        --build-arg VERSION="$version" \
+        -t "$("$SCRIPT_DIR/projectname")" .
 }
 
 main "$@"
diff --git a/script/frontend-check b/script/frontend-check
index c2b8314..0819860 100755
--- a/script/frontend-check
+++ b/script/frontend-check
@@ -1,9 +1,9 @@
 #!/bin/sh
 # script/frontend-check: run the frontend half of the checks only (test,
-# lint, fmt-check). This exists for the frontend Dockerfile, whose build
-# stage is a node image with neither Go nor Docker; the backend half is
-# gated by Dockerfile.backend. Everywhere else, use script/check, which
-# covers the whole repo. Must not modify any files.
+# lint, fmt-check). This exists for the frontend stage of Dockerfile, a
+# node image with neither Go nor Docker; the Dockerfile's lint and
+# backend build stages gate the backend half. Everywhere else, use
+# script/check, which covers the whole repo. Must not modify any files.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
diff --git a/script/lint b/script/lint
index 8eea8a2..1b3783d 100755
--- a/script/lint
+++ b/script/lint
@@ -3,8 +3,8 @@
 # Go linter over backend/.
 #
 # The Go linter runs only in Docker: this builds the lint stage of
-# Dockerfile.backend, the digest-pinned golangci-lint image, which runs
-# the backend's fmt-check and lint targets. --no-cache makes the linter
+# Dockerfile, the digest-pinned golangci-lint image, which runs the
+# backend's fmt-check and lint targets. --no-cache makes the linter
 # really run every time rather than reuse an earlier result, and the
 # stage is built for its checks alone, so no image is kept.
 set -eu
@@ -15,7 +15,7 @@ main() {
     cd "$ROOT"
     "$ROOT/script/frontend-lint"
     timeout 300 docker build --no-cache --target lint \
-        --output type=cacheonly -f Dockerfile.backend .
+        --output type=cacheonly .
 }
 
 main "$@"