diff --git a/docker-compose.local.yml b/docker-compose.local.yml
new file mode 100644
index 0000000..c41b6b2
--- /dev/null
+++ b/docker-compose.local.yml
@@ -0,0 +1,40 @@
+# Local development / smoke-test compose file.
+# Unlike docker-compose.example.yml (which pulls a pre-built image from a registry),
+# this file BUILDS the image from the local Dockerfile so you can iterate without
+# pushing anywhere.
+#
+# Usage:
+#   1. Copy .env.example to .env and fill in UPDATER_API_KEY (e.g. `openssl rand -hex 32`)
+#   2. Optionally adjust STACKS_ROOT below to point at a directory you actually have
+#      compose stacks in (default points at this repo dir, which is fine for smoke tests)
+#   3. docker compose -f docker-compose.local.yml up --build
+#   4. curl -s http://localhost:8080/healthz | jq
+#   5. curl -sH "Authorization: Bearer $UPDATER_API_KEY" -d '{"image":"test"}' \
+#        http://localhost:8080/update | jq
+
+services:
+  package-updater:
+    build:
+      context: .
+      args:
+        VERSION: dev-local
+        COMMIT: ${COMMIT:-unknown}
+        BUILD_TIME: ${BUILD_TIME:-unknown}
+    container_name: package-updater-local
+    restart: unless-stopped
+    environment:
+      - UPDATER_API_KEY=${UPDATER_API_KEY}
+      - STACKS_ROOT=${STACKS_ROOT:-/tmp}
+      - LOG_LEVEL=debug
+      - PORT=8080
+      - UPDATE_TIMEOUT=5m
+    ports:
+      - "8080:8080"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${STACKS_ROOT:-/tmp}:${STACKS_ROOT:-/tmp}:ro
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O-", "http://localhost:8080/healthz"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
diff --git a/env.sample b/env.sample
new file mode 100644
index 0000000..8d4badb
--- /dev/null
+++ b/env.sample
@@ -0,0 +1,15 @@
+# Copy to .env (which is gitignored) and fill in real values:
+#   cp env.sample .env && $EDITOR .env
+
+# Required: bearer token clients must send as `Authorization: Bearer <value>`.
+# Generate with: openssl rand -hex 32
+UPDATER_API_KEY=
+
+# Optional: root directory the service is allowed to manage stacks under.
+# Defaults to /tmp for local smoke testing. For real use, set to your stacks dir,
+# e.g. /home/shcizo/self-hosted
+# STACKS_ROOT=/home/shcizo/self-hosted
+
+# Optional: build info baked into the binary via -ldflags. Not required.
+# COMMIT=$(git rev-parse --short HEAD)
+# BUILD_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)