Add Docker containerization of unreal-index service

[Joxx0r]

Summary

• Replace manual WSL setup (Node 22, Go, Zoekt build, screen) with docker compose up
• Multi-stage Dockerfile: Go builder (Zoekt binaries) → Node builder (native modules) → slim runtime (~250MB)
• Named Docker volumes for SQLite, mirror, and Zoekt index (ext4, survives docker compose down)

Changes

New files (8)

File	Purpose
Dockerfile	3-stage build: Go (Zoekt), Node (native deps), slim runtime
docker-compose.yml	Production: named volumes, 4GB mem limit, healthcheck, graceful shutdown
docker-compose.dev.yml	Dev override: source mounts, --watch, Zoekt port exposed
config.docker.json	Container paths (/data/), host: 0.0.0.0, empty projects
docker-entrypoint.sh	Creates data dirs, copies default config, exec node for signal handling
.dockerignore	Excludes tests, artifacts, git history
test-docker-perf.mjs	6-phase Docker perf test (startup, core, restart, ingest-under-load, memory, volume I/O)
DOCKER.md	Setup guide, architecture diagram, troubleshooting, Docker-vs-WSL comparison

Modified files (2)

File	Change
src/service/index.js	UNREAL_INDEX_CONFIG env var override + relaxed project validation (warning instead of error for empty projects)
start-service.sh	--docker flag: runs docker compose up -d and polls health for 30s

Design decisions

Concern	Solution
SQLite perf	Named volumes (ext4 on Docker VM), NOT bind mounts from Windows
Data persistence	3 named volumes survive down. Only down -v destroys them
Memory	4GB container limit (3GB Node heap + 1GB Zoekt/OS)
Graceful shutdown	stop_grace_period: 30s + exec entrypoint for direct SIGTERM
Networking	Port 3847 mapped to host. Zoekt 6070 internal only

Test plan

• docker compose build completes without errors
• docker compose up -d starts, curl localhost:3847/health responds within 30s
• Windows watcher can POST to localhost:3847/internal/ingest and data persists
• docker compose down && docker compose up -d retains all indexed data
• node test-docker-perf.mjs passes all 6 phases
• docker compose -f docker-compose.yml -f docker-compose.dev.yml up works for dev

🤖 Generated with Claude Code

[github-actions]

@claude Please review this PR. Focus on:

• Code quality and potential bugs
• Security issues
• Test coverage
• Documentation completeness

Use the opus model for thorough analysis.

[Joxx0r]

@claude could you review this?

[Joxx0r]

@claude could you review this

[claude]

Solid Docker foundation. The multi-stage build is well structured and the named-volume persistence model is the right call for SQLite performance. Two issues to address:

1. Zoekt pinned to @latest — not reproducible, supply chain risk

RUN go install github.com/sourcegraph/zoekt/cmd/zoekt-index@latest &&
go install github.com/sourcegraph/zoekt/cmd/zoekt-webserver@latest

@latest resolves at build time to whatever the head commit is. This means:

• Two builds on different days can produce different binaries
• A breaking Zoekt release silently breaks the image
• The image is not auditable (no way to know which Zoekt version is running)

Pin to a specific release tag or commit hash. Check the Zoekt releases page for the current stable tag and use that, e.g. @v0.0.0-20250101000000-abcdef123456 or a tagged release.

2. src/blueprint-test.js is not excluded from the Docker image

.dockerignore excludes src/*.test.js (matching wsl-migration.test.js), but src/blueprint-test.js does not match that pattern and is therefore included in the production image. Add it explicitly:

src/blueprint-test.js

or broaden the glob to also catch *-test.js files.

Other notes (no action required)

• memswap_limit: 4g equal to mem_limit: 4g intentionally sets swap to 0 — this is documented in the design decisions and is correct.
• UNREAL_INDEX_CONFIG env override in index.js is clean and the empty-projects warning is the right behavior for Docker.
• docker-entrypoint.sh using exec node gives correct signal propagation.
• Healthcheck using node -e "fetch(...)" is fine on Node 22.