Skip to content

feat: add gateway to OSS docker deploy with auto-registration#854

Open
harshithmullapudi wants to merge 8 commits into
mainfrom
plan-add-gateway-to-oss-deploy
Open

feat: add gateway to OSS docker deploy with auto-registration#854
harshithmullapudi wants to merge 8 commits into
mainfrom
plan-add-gateway-to-oss-deploy

Conversation

@harshithmullapudi
Copy link
Copy Markdown
Member

@harshithmullapudi harshithmullapudi commented May 15, 2026

Summary

  • Gateway compose overlay (hosting/docker/docker-compose.gateway.yaml): new file that adds the corebrain-gateway service to the OSS stack when run with -f. The gateway joins the existing core Docker network so it can reach the webapp at http://core:3000 internally. Includes depends_on: core, shared logging config, and platform: linux/amd64 note.

  • .env.example updated (hosting/docker/.env.example): documents all gateway env vars in one place — COREBRAIN_GATEWAY_SECURITY_KEY, COREBRAIN_API_KEY, COREBRAIN_DEFAULT_GATEWAY_* for auto-registration, GATEWAY_VERSION, COREBRAIN_GATEWAY_HTTP_PORT, agent credentials.

  • Docs added (hosting/docker/README.md): operator guide covering quick start, two-file compose invocation, env var wiring table, auto-registration setup, and first-boot key-from-logs flow.

  • Webapp auto-registration (3 files): when COREBRAIN_DEFAULT_GATEWAY_URL and COREBRAIN_DEFAULT_GATEWAY_SECURITY_KEY are both set, the webapp calls registerGateway() for every new workspace created. Idempotent (re-registration updates the existing row). Never fails workspace creation — errors are caught and logged with [default-gateway] prefix.

Usage

# Start full stack with gateway
cd hosting/docker
cp .env.example .env  # set COREBRAIN_GATEWAY_SECURITY_KEY + COREBRAIN_DEFAULT_GATEWAY_*
docker compose -f docker-compose.yaml -f docker-compose.gateway.yaml up -d

New env vars (webapp)

Var Required Purpose
COREBRAIN_DEFAULT_GATEWAY_URL No URL the webapp uses to reach the gateway (triggers auto-registration when set)
COREBRAIN_DEFAULT_GATEWAY_SECURITY_KEY If URL set Security key for verifying the gateway
COREBRAIN_DEFAULT_GATEWAY_NAME No DB name for the auto-registered gateway (default: local-gateway)

Files changed

File Change
hosting/docker/docker-compose.gateway.yaml New — gateway compose overlay
hosting/docker/.env.example +31 lines — gateway env block
hosting/docker/README.md New — operator docs
hosting/docker/docker-compose.yaml +3 lines — pass COREBRAIN_DEFAULT_GATEWAY_* to core service
apps/webapp/app/env.server.ts +5 lines — Zod schema for 3 new env vars
apps/webapp/app/services/gateway/default.server.ts New — maybeRegisterDefaultGateway (36 lines)
apps/webapp/app/models/workspace.server.ts +11 lines — call in createWorkspace()

Test plan

  • docker compose -f docker-compose.yaml -f docker-compose.gateway.yaml up -d starts both services without error
  • Gateway container is reachable at localhost:7787
  • Setting COREBRAIN_DEFAULT_GATEWAY_URL=http://corebrain-gateway:7787 and COREBRAIN_DEFAULT_GATEWAY_SECURITY_KEY=<key> causes the gateway to appear in the workspace sidebar after signup
  • Leaving both vars unset has no effect (returns early, no log noise)
  • Restarting the stack with both vars set does not create duplicate gateway records
  • If the gateway is unreachable, workspace creation still succeeds and a warn log appears

🤖 Generated with Claude Code

harshithmullapudi and others added 8 commits May 15, 2026 04:37
@harshithmullapudi @claude
feat: add docker-compose.gateway.yaml overlay for co-located gateway
8a9147a 
Adds a Docker Compose overlay that lets users bring up the CoreBrain
gateway alongside the core stack with a single two-file compose command.
The gateway joins the internal `core` network so it talks to the webapp
at http://core:3000 without exposing the API publicly, and uses
${GATEWAY_VERSION:-latest} to allow version pinning via .env.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@harshithmullapudi @claude
feat: add gateway env vars to hosting/docker/.env.example
16bb55d 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@harshithmullapudi @claude
docs: add hosting/docker/README.md for core + gateway Docker Compose …
5e7efcc 
…setup

Covers quick-start (core only), running both compose files with -f, env
var wiring, auto-registration via DEFAULT_GATEWAY_URL, and how to
retrieve the auto-generated security key from container logs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@harshithmullapudi @claude
docs: add hosting/docker/README.md for core + gateway Docker Compose …
2b02653 
…setup

Also pass DEFAULT_GATEWAY_URL, DEFAULT_GATEWAY_NAME, COREBRAIN_GATEWAY_SECURITY_KEY
env vars through to the core service in docker-compose.yaml so auto-registration works.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@harshithmullapudi @claude
feat: auto-register default gateway for new workspaces
489877c 
When DEFAULT_GATEWAY_URL and COREBRAIN_GATEWAY_SECURITY_KEY env vars
are set, every newly-created workspace automatically registers the
configured gateway with no user action required. Registration failures
are logged but never block workspace creation.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@harshithmullapudi @claude
fix: rename gateway env vars to COREBRAIN_DEFAULT_GATEWAY_* prefix
633ec23 
- Rename DEFAULT_GATEWAY_URL → COREBRAIN_DEFAULT_GATEWAY_URL
- Rename DEFAULT_GATEWAY_NAME → COREBRAIN_DEFAULT_GATEWAY_NAME
- Add COREBRAIN_DEFAULT_GATEWAY_SECURITY_KEY (distinct from the gateway
  container's own COREBRAIN_GATEWAY_SECURITY_KEY, same value)
- Add defensive try/catch at workspace.server.ts call site
- Update .env.example, docker-compose.yaml passthrough, and README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@harshithmullapudi @claude
test: add unit tests for maybeRegisterDefaultGateway
1e6d8f7 
15 tests covering:
- Guard conditions (missing URL, key, both, empty string)
- Successful registration with correct args
- Custom gateway name from env
- Success logging
- Failure logging (ok: false)
- Error resilience (registerGateway throws → logged, not re-thrown)
- Idempotency pass-through to registerGateway

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@harshithmullapudi @claude
refactor: use hosting/gateway/docker-compose.yaml instead of overlay
bf48bed 
- Delete hosting/docker/docker-compose.gateway.yaml (duplicate overlay)
- Update README to instruct running both compose files from the repo root:
    docker compose \
      -f hosting/docker/docker-compose.yaml \
      -f hosting/gateway/docker-compose.yaml \
      up -d
- Document network topology: gateway reaches webapp via host-exposed port
  (COREBRAIN_API_URL), not Docker internal DNS, since the two services are
  on different Docker networks
- Update .env.example: COREBRAIN_API_URL + COREBRAIN_DEFAULT_GATEWAY_URL
  now documented with host.docker.internal examples instead of Docker
  service-name addresses

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@harshithmullapudi