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

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
 

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`.

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"),

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
+}

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,

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)
+			}
+		})
+	}
+}

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()

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)}"

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.