wishforge-ide/docs/operations.md
eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
Imports the previously untracked working tree as-is so that the review
changes that follow (requirements -> design -> implementation) can be
reviewed as diffs and reverted if needed. No content changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:18:04 +08:00

12 KiB

Local operations and deployment runbook

Development startup

Requirements: Node 22+, npm, Docker Compose. On this Mac use explicit docker --context colima; do not change another project's Docker context or stop its services. All services belong to Compose project wishforge-dev.

docker --context colima compose -f infra/compose.yaml up -d
docker --context colima compose -f infra/compose.yaml ps
npm run setup:local
npm run db:migrate
npm run db:seed

The setup creates private, ignored .env.local files and a random password for the RLS-enforced wishforge_app database role. Run the API with DATABASE_URL from that generated file. DATABASE_ADMIN_URL is migration-only. Keep the administration login out of the running API, workers and IDE.

Service Local address Development fixture
Web http://localhost:3000 Root web start command
API / MCP http://127.0.0.1:4000 / /mcp Root API start command
Theia http://127.0.0.1:4300 Independent apps/ide installation
PostgreSQL 127.0.0.1:55432 wishforge / wishforge-dev-only admin
Temporal 127.0.0.1:7233 UI http://127.0.0.1:8233
Keycloak http://127.0.0.1:4100 Admin admin / wishforge-admin-dev-only
Demo OIDC user Realm wishforge demo / wishforge-demo-dev-only
S3 / Console http://127.0.0.1:49000 / :49001 wishforge-dev / wishforge-minio-dev-only
Registry http://127.0.0.1:45000 Local unauthenticated development registry
OCT http://127.0.0.1:48100 ide profile; local simple login only

These credentials are deliberately public local fixtures. start-dev, public fixture passwords, simple OCT login and the local registry are prohibited as production defaults. Keycloak realm import happens on first setup; editing the JSON does not update an already imported realm. Apply reviewed fixture changes through administration, or recreate only disposable WishForge dev state when explicitly desired. Never casually use down -v.

The Temporal image runs as UID 1000. An idempotent local init service initializes its dedicated volume ownership before start. It uses a persisted SQLite development server, not production Temporal storage. The S3 init creates private artifacts, workspaces and evidence buckets and enables versioning for evidence; versioning is not immutable/WORM retention.

IDE and collaboration

docker --context colima compose -f infra/compose.yaml --profile ide build oct
docker --context colima compose -f infra/compose.yaml --profile ide up -d oct
cd apps/ide
PUPPETEER_SKIP_DOWNLOAD=true npm ci
npm run plugins:download
npm run build
npm start

OCT is fixed at 0.3.1 with ws 8.21.0 overridden in its independent lockfile. The image deliberately runs lib/app.js; the upstream oct-server executable runs a prebundled dependency graph that would bypass that override. The upstream 0.3.1 --port parser yields NaN when passed an explicit port, so the image uses its default port 8100. These choices were discovered by actual startup/audit tests.

If a local Docker build fails because docker-credential-desktop is absent, use an isolated temporary empty Docker configuration for public image builds and an explicit daemon socket; preserve the user's actual Docker config. Never copy private registry credentials into source or build args. Prefer repairing the local helper installation when private images are needed.

Verification and shutdown

WF_DOCKER_CONTEXT=colima node infra/scripts/smoke.mjs --ide
kubectl kustomize infra/k8s/base > /tmp/wishforge-k8s-rendered.yaml

The smoke script checks PostgreSQL queries, Temporal gRPC health/UI, OIDC issuer and PKCE metadata, S3 readiness, registry v2, and optional OCT metadata. It does not claim an actual desktop OAuth flow or multi-user editing has passed. Stop only this project with docker --context colima compose -f infra/compose.yaml --profile ide stop. Data volumes are retained.

Production and BYO handoff

Render and review infra/k8s/base, then use the intended cluster context explicitly. Before any production deployment, provide actual ingress/DNS/TLS, service images by digest, secrets via external management, production data services, admission rules, node RuntimeClass installation, CNI policies and backup/restore evidence. The base default-denies networking intentionally; allow the exact required flows in an environment overlay. infra/k8s/examples/runner-job.yaml is a template with an invalid placeholder image and references only an externally created scoped capability Secret. It is not a runnable production release.

BYO acceptance must occur on the customer's actual enrolled target: validate the target identity, architecture, artifact digest, config/secret versions, health, business flow, revoked enrollment, timeout reconciliation and rollback. Local Compose success is not BYO customer acceptance.

During rollback, stop new assignments first, revoke affected run capabilities, switch to the prior stable release/Bundle and verify readback. Keep in-flight workflow and schema compatibility. Never interpret application rollback as permission to reverse a destructive data migration.

Local Git and authenticated IDE services

After npm run setup:local, run each long-lived service in its own terminal from the repository root. .env.local contains generated private credentials; never paste those values into logs or commands.

node --env-file=.env.local --import tsx apps/git-service/src/main.ts
node --env-file=.env.local apps/ide/gateway/main.mjs

Git uses WF_GIT_PORT (4504), independently of the API's PORT. New projects receive a real initialized main branch and its SHA. The Git admin token is only for repository/token administration; workers receive short-lived repository-scoped read/write capabilities. Git URLs contain no bearer tokens. Existing server-side repository symlinks are rejected. Keep the storage root private and backed up; repository-provision lock recovery requires checking that no initializer is active.

Run Theia with WISHFORGE_WORKSPACE_PATH pointing to one dedicated project directory and THEIA_CONFIG_DIR pointing to its own configuration directory. Do not expose port 4300 beyond loopback locally; production uses the private service and gateway. Theia's own process token stays in the gateway, never in the client session or logs. WF_IDE_ALLOWED_SERVICE_NAMESPACE permits only the provisioner's exact hashed wf-ide-<24 hex>.<namespace>.svc:3000 service names; no arbitrary DNS suffix is trusted.

The pinned collaboration package is present, but @wishforge/ide-policy registers room commands/status only for a configured, same-origin workspace gateway route. The startup wrapper has no public OCT fallback. Local OCT is a compatibility fixture, not authorized production collaboration. Enablement requires the workspace-specific OCT instance and authenticated gateway route described below; a deployment flag alone is not sufficient.

Reproducible local blue-green acceptance

Use a verified Caddy 2.10.2 executable in a temporary directory (official release: https://github.com/caddyserver/caddy/releases/tag/v2.10.2). It is not installed globally. The test requires free loopback ports 45219/45280, the existing WishForge registry on 45000 and cached/public node:22.14.0-bookworm-slim. It refuses an occupied admin endpoint and never uses the default Docker context.

WF_COMPOSE_ACCEPTANCE=true WF_CADDY_BINARY=/absolute/path/to/caddy \
  node --import tsx infra/scripts/compose-acceptance.mjs
node --test apps/ide/gateway/test/*.test.mjs apps/ide/provisioner/test/*.test.mjs
npx vitest run packages/runtime/test apps/git-service/test apps/runner/test

The test makes real images and temporary local containers; its cleanup scope is its randomly named Compose projects, networks and image tag. Development registry blobs remain for normal retention. The controlled Caddy path is one reverse-proxy handler, read with ETag and changed with If-Match (https://caddyserver.com/docs/api). Never give the coding process the deployment runner's Docker socket, proxy admin endpoint or cluster service account. Loopback alone is not isolation from untrusted processes on the same host; production needs a separate deployment trust boundary.

Compose/Kubernetes candidate identity includes the source SHA, image digest, architecture, configuration version/content, release binding and protected checks. Changing these requires a new release ID. A post-cutover business failure restores an existing prior route using CAS, never an unconditional overwrite. Secret version references use the deployment-only Vault KV v2 broker, whose public mapping digest is bound to the approved release. Missing configuration, mapping drift or an unavailable exact version fails closed. Compose receives private child-process placeholders; Kubernetes receives a same-namespace immutable Secret through stdin. No secret values are stored in control-plane records or rendered plans.

Scoped collaboration integration (default off)

The gateway now supports /workspaces/:id/collaboration/ for a separate OCT instance per workspace. Its upstream must come from the authorized workspace record and match WF_COLLABORATION_ALLOWED_UPSTREAM_ORIGINS locally or the exact managed workspace service on port 8100. Every HTTP request and Socket.IO upgrade requires edit permission; open sockets are reauthorized and terminated on revoke. OCT display names, invitations and login tokens never replace platform access.

Theia's policy extension only registers collaboration commands when WF_COLLABORATION_GATEWAY_URL points to the browser's same origin and exact current workspace prefix. It supplies an explicit Engine.IO path; merely setting OCT's base URL would select the wrong Socket.IO namespace. Without that setting, collaboration stays disabled, and the public OCT demonstration service is never used. Use apps/ide/collaboration/start-isolated.mjs/Dockerfile for a dedicated instance; fresh per-process signing keys invalidate room capabilities at restart. OCT still stores rooms in memory: saved files remain, but clients must create a new room and rejoin after a restart. Unsaved draft recovery and debugger controller semantics remain separate acceptance requirements.

Saved revisions, draft recovery and debug control

The Theia policy extension now supplies these actual command-palette actions: WishForge: Create Verified Workspace Snapshot, Recover Unsaved Draft, Acquire Debug Control, Transfer Debug Control, and Release Debug Control. Before starting F5 debugging, acquire control. The backend enforces the lease on both native DAP and bundled VS Code debug-plugin RPC; another tab's same actor cannot silently take its token.

Generate a local fixture key pair with node apps/ide/security/create-local-keys.cjs. Set the private key path only on the gateway (WF_IDE_GATEWAY_PRIVATE_KEY_FILE) and the public key path on Theia (WF_IDE_GATEWAY_PUBLIC_KEY_FILE). Theia additionally requires WF_TENANT_ID, WF_WORKSPACE_ID, and WF_COORDINATION_STATE_DIR, which must be separate from WISHFORGE_WORKSPACE_PATH. Never mount the gateway private key into the workspace.

Snapshot manifests/blobs and saved revisions persist in the coordination directory; client membership, acknowledgements and debug leases are intentionally reset on a backend restart. Dirty browser drafts persist in actor/workspace-scoped IndexedDB. Recovery compares a draft with the current saved content and opens an unsaved copy. It does not silently overwrite newer source files. Snapshot limits default to 32 MiB per file, 256 MiB total source and 20,000 files; local draft+baseline is limited to 2 MiB UTF-8. Quota/ack/version failures report refusal, not a saved revision.

This remains a same-UID Theia/terminal deployment. A separate state directory/PVC is not inaccessible to a malicious terminal with that UID. Production must not claim hostile-editor hard isolation or use its snapshot as independent release verification. See apps/ide/policy/README.md for the distinct gateway/sidecar and managed-debugger isolation needed for that threat model.