Docker containerization for index service

[Joxx0r]

Motivation

The unreal-index service currently runs in WSL2 with a complex manual installation: Node 22, Go 1.24, Zoekt built from source, systemd user service, and specific PATH configuration. This makes onboarding new team members difficult and Zoekt process management fragile.

Containerizing the WSL-side components (Node.js service + Zoekt) into a single Docker container simplifies installation to docker compose up -d while preserving the existing Windows watcher and MCP bridge unchanged.

Architecture

Windows Host                          Docker Container (Linux)
┌──────────────────┐                 ┌──────────────────────────┐
│ Watcher           │  HTTP POST     │  tini (PID 1)            │
│ (watcher-client)  │───────────────►│  └─ node service/index.js│
│                   │  :3847         │      ├─ Express API :3847 │
│ MCP Bridge        │  HTTP GET      │      ├─ SQLite (WAL)     │
│ (mcp-bridge)      │───────────────►│      ├─ Memory Index     │
│                   │  :3847         │      └─ zoekt-webserver   │
└──────────────────┘                 │          └─ :6070 (int)   │
                                     │                           │
                                     │  Volumes:                 │
                                     │  /data/db     (SQLite)    │
                                     │  /data/mirror (Zoekt src) │
                                     │  /data/zoekt-index (shards)│
                                     └──────────────────────────┘

Implementation (on docker-image branch)

New Files

File	Purpose
Dockerfile	Multi-stage build: Go builder (Zoekt binaries), Node builder (native deps), slim runtime with tini
docker-entrypoint.sh	Ensure /data dirs, copy default config, exec node service
config.docker.json	Docker-specific defaults: 0.0.0.0 host, /data/* paths, empty projects
docker-compose.yml	Single service, 3 named volumes, 5GB mem limit, restart policy
docker-compose.dev.yml	Dev overlay: source mounts, node --watch, exposed Zoekt port
.dockerignore	Exclude node_modules, .git, test artifacts, Windows-only files
DOCKER.md	Full documentation: quick start, architecture, config, troubleshooting

Modified Files

File	Change
src/service/index.js	Allow empty projects array (log warning instead of throwing), update platform check error message
.gitattributes	Ensure LF endings for Dockerfile and entrypoint

What's NOT Changed

Watcher, MCP bridge, zoekt-manager, zoekt-client, zoekt-mirror, api.js, memory-index, database — all unchanged.

Memory Budget

Consumer	Allocation
Node.js V8 heap	up to 3 GB
SQLite page cache	~256 MB
Zoekt webserver	~150-200 MB
Zoekt indexer (transient)	~200-500 MB

Container limits: 5 GB RAM + 2 GB swap safety net.

Verification Checklist

• docker compose build succeeds
• docker compose up -d starts healthy within 60s
• curl http://localhost:3847/health returns ok
• Watcher ingest works (non-zero counts in /internal/status)
• Grep search returns results
• Graceful shutdown within 15s
• Data persists across restart (volumes intact)
• Memory stays under 5GB during startup + indexing