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