chore(docker): add compose override for local server development

[YoavLev]

What changed?

Added docker/docker-compose-local-server.yml — a docker-compose override file that stubs out the Cadence server container while keeping all infrastructure dependencies running in Docker.

Why?

Working on and testing the Cadence server and system workflows locally is difficult because of the heavy infrastructure requirements (Elasticsearch, Kafka, Cassandra, Prometheus, Grafana). The existing docker-compose files bundle the server with these dependencies, forcing developers to either run everything in Docker (losing native debugging, fast rebuild cycles, and IDE integration) or manually set up each dependency.

This override file lets developers run only the infrastructure in Docker while running the server natively from the local repository. It:

• Replaces the Cadence server container with a no-op busybox stub
• Reconfigures Kafka to advertise on 127.0.0.1 so the host-running server can connect
• Points cadence-web to host.docker.internal to reach the locally running server

Usage:

# Start infrastructure dependencies
docker compose -f docker/docker-compose-es-v7.yml -f docker/docker-compose-local-server.yml up

# Install schema (first time only)
make bins && make install-schema

# Run the server locally
./cadence-server start

How did you test it?

1. Started infrastructure with the override:
   docker compose -f docker/docker-compose-es-v7.yml -f docker/docker-compose-local-server.yml up
2. Installed schema: make install-schema
3. Built and ran the server locally: make cadence-server && ./cadence-server start
4. Verified cadence-web at localhost:8088 connects to the local server
5. Validated merged compose config: docker compose -f docker/docker-compose-es-v7.yml -f docker/docker-compose-local-server.yml config

Potential risks

None. This is a new additive file with no changes to existing files. Requires Docker Compose v2.24+ for !reset directive support.

Release notes

N/A — developer tooling only.

Documentation Changes

Could add a note to CONTRIBUTING.md about this local development option, but not strictly required as the file is self-documenting with usage instructions in the header comments.

[gitar-bot]

Please add a reference to a cadence-workflow GitHub issue in the PR description. Use one of the accepted formats, for example: Fixes #123, cadence-workflow/cadence#123, or a full issue URL.

[gitar-bot]

Please link a cadence-workflow issue in the PR description.

Details

No valid cadence-workflow issue link was found. Add one in any of the accepted formats:

• Fixes #123
• cadence-workflow/repo#123
• https://github.com/cadence-workflow/repo/issues/123

[gitar-bot]

Code Review 👍 Approved with suggestions 0 resolved / 1 findings

Adds a Docker Compose override file to streamline local server development setup. Consider testing host.docker.internal resolution on Linux Docker Engine, as it may require additional configuration or fallback handling.

💡 Edge Case: host.docker.internal may not resolve on Linux Docker Engine

📄 docker/docker-compose-local-server.yml:22

host.docker.internal is not automatically available on Linux when using Docker Engine (non-Desktop). It works out-of-the-box on Docker Desktop for macOS/Windows/Linux, but on bare Docker Engine (common in Linux dev setups) it requires an explicit extra_hosts mapping. This is an existing pattern in the repo (grafana, prometheus configs), so it's not new to this PR, but since this file targets local development it may be worth adding the mapping or at least documenting the requirement in the header comment.

Suggested fix

# Add to the cadence-web service:
  cadence-web:
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - "CADENCE_GRPC_PEERS=host.docker.internal:7833"

🤖 Prompt for agents

Code Review: Adds a Docker Compose override file to streamline local server development setup. Consider testing `host.docker.internal` resolution on Linux Docker Engine, as it may require additional configuration or fallback handling.

1. 💡 Edge Case: `host.docker.internal` may not resolve on Linux Docker Engine
   Files: docker/docker-compose-local-server.yml:22

   `host.docker.internal` is not automatically available on Linux when using Docker Engine (non-Desktop). It works out-of-the-box on Docker Desktop for macOS/Windows/Linux, but on bare Docker Engine (common in Linux dev setups) it requires an explicit `extra_hosts` mapping. This is an existing pattern in the repo (grafana, prometheus configs), so it's not new to this PR, but since this file targets local development it may be worth adding the mapping or at least documenting the requirement in the header comment.

   Suggested fix:
   # Add to the cadence-web service:
     cadence-web:
       extra_hosts:
         - "host.docker.internal:host-gateway"
       environment:
         - "CADENCE_GRPC_PEERS=host.docker.internal:7833"

Rules ⚠️ 1/2 requirements met

Repository Rules

❌ GitHub Issue Linking Requirement: Add a reference to a cadence-workflow issue in the PR description using one of these formats: 'Fixes #123', 'cadence-workflow/repo#123', or 'https://github.com/cadence-workflow/repo/issues/123'.

✅ PR Description Quality Standards: All required sections are present and contain substantive, concrete content including copyable test commands, a clear rationale, and appropriate N/A justifications.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}