feat: add Docker Compose setup for local development#278
Open
kiloconnect[bot] wants to merge 12 commits intomainfrom
Open
feat: add Docker Compose setup for local development#278kiloconnect[bot] wants to merge 12 commits intomainfrom
kiloconnect[bot] wants to merge 12 commits intomainfrom
Conversation
![kiloconnect[bot]](https://avatars.githubusercontent.com/in/2193792?s=60&v=4){kind=small}
Contributor
Author
Code Review SummaryStatus: 1 Issue Found | Recommendation: Address before merge Overview
Issue Details (click to expand)WARNING
Files Reviewed (5 files)
|
- DOCKER_DEV.md: document that network_mode: host is Linux-only - Dockerfile.dev: pin wrangler to 4.61.1 for reproducibility - Dockerfile.dev: pin bun to v1.2.5 for reproducibility - docker-compose.dev.yml: fix postgres volume path to /var/lib/postgresql/data - docker-compose.dev.yml: remove pnpm install from nextjs container command
…bility - Replace network_mode: host with explicit ports: mappings (host networking is Linux-only and doesn't work on Docker Desktop for macOS) - Add --ip 0.0.0.0 to wrangler dev commands so services bind to all interfaces inside the container (required for port forwarding) - Add extra_hosts for host.docker.internal resolution - Update DOCKER_DEV.md: remove ss command (Linux-only), use lsof only, update architecture section to reflect ports-based approach - Change prerequisite from Docker 20.10+ to Docker Desktop 4.x+
- Add dev/docker-wrangler-entrypoint.sh that patches wrangler.jsonc at startup, replacing localhost references with Docker service names (e.g., localhost:3000 → nextjs:3000, localhost:5432 → postgres:5432) - Override Next.js env vars (POSTGRES_URL, CLOUD_AGENT_API_URL, WEBHOOK_AGENT_URL) in docker-compose to use Docker service names - Add networking documentation to DOCKER_DEV.md explaining how inter-service communication works on the bridge network - Workers now use the entrypoint script instead of raw pnpm dev, which also handles predev scripts (e.g., cloud-agent wrapper build) All services share the default Docker Compose bridge network and reach each other by service name via Docker DNS. No network_mode: host needed, so this works on both macOS (Docker Desktop) and Linux.
- Pin node base image to 22.14.0-slim for reproducibility - Pin pgvector/pgvector to 0.8.0-pg18 for consistent local-dev behavior - Add argument validation in docker-wrangler-entrypoint.sh - Fix repo name in Makefile header (kilocode-backend → Kilo-Org/cloud) - Update Docker prerequisite wording to cover Linux (Docker Engine) - Add pnpm preflight check in dev.sh, drop --frozen-lockfile for local dev - Use exec-form command for nextjs service (proper PID1 signal handling)
…to loopback - DOCKER_DEV.md: fix env_file reference to match actual ../.env path in compose - docker-compose.dev.yml: bind postgres port to 127.0.0.1 to prevent network exposure on Linux
Co-authored-by: kiloconnect[bot] <240665456+kiloconnect[bot]@users.noreply.github.com>
Co-authored-by: kiloconnect[bot] <240665456+kiloconnect[bot]@users.noreply.github.com>
Contributor
Author
|
Fixed the cross-profile dependency issue: added |
… exposure All 14 remaining worker services now use 127.0.0.1:PORT:PORT port mappings, matching postgres, nextjs, and cloud-agent. This prevents accidental exposure on all network interfaces on Linux Docker Engine.
Workers that use container-backed Durable Objects (cloud-agent, cloud-agent-next, cloudflare-app-builder, cloudflare-deploy-builder) need Docker to spawn sandbox containers via Wrangler. Since these workers already run inside Docker, they can't use Docker natively. Mount /var/run/docker.sock into these 4 services so Wrangler can talk to the host Docker daemon to create sibling containers.⚠️ This grants the container full control over the host's Docker daemon — acceptable for local dev, never for production. Also documents the requirement and security trade-off in DOCKER_DEV.md.
| # kiloclaw | ||
| ``` | ||
|
|
||
| > **Note:** You do NOT need to change `localhost` references in `.dev.vars` files for Docker — the entrypoint script handles URL rewriting automatically via the wrangler.jsonc patching. |
Contributor
Author
There was a problem hiding this comment.
[WARNING]: .dev.vars connection URLs with localhost will break in Docker — entrypoint only patches wrangler.jsonc
This note says .dev.vars localhost references don't need changing, but that's only true for CORS-style values (e.g., WS_ALLOWED_ORIGINS). Connection URLs like API_URL=http://localhost:3000 in cloudflare-code-review-infra/.dev.vars will break because:
- The entrypoint script only patches
wrangler.jsonc, not.dev.vars - Wrangler's
.dev.varssecrets overridewrangler.jsoncvars for the same key - Inside the container,
localhost:3000points to the container itself, not thenextjsservice
Consider either:
- Updating this note to clarify that connection URLs in
.dev.vars(likeAPI_URL) do need to be changed to use Docker service names - Or extending
docker-wrangler-entrypoint.shto also patch.dev.varsfiles
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a Docker Compose-based local development setup so developers can start the entire stack (Next.js backend + all Cloudflare Workers) with a single command instead of opening ~6 separate terminals.
Changes
dev/Dockerfile.dev— Shared dev image (Node 22 + pnpm + wrangler + bun, all pinned)dev/docker-compose.dev.yml— Orchestrates all 17 services (PostgreSQL + Next.js + 15 workers) with profile supportdev/dev.sh— Startup script with preflight checksDOCKER_DEV.md— Full documentation (prerequisites, quick start, port map, troubleshooting)Makefile— Convenience targets (make dev-docker,make dev-docker-core, etc.)Usage
Port Map
Notes
ports:mappings for macOS (Docker Desktop) compatibilitydev/docker-compose.yml(PostgreSQL-only) continues to work standaloneBuilt for Igor by Kilo for Slack
Built for Evgeny Shurakov by Kilo for Slack