EmbarkStudios / EmbarkStudios/UnrealClaudeFileHelper

Docker containerization for index service

Open
#43 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
17
Forks
1
PR merge metrics
No merged PRs in 30d

Description

## 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

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.