Skip to main content

Existing environment (bring your own infra)

Use this when you already have Docker host(s) (a VM, an on-prem box, an existing cloud instance) and want to run Cortega directly, with no provisioning script and no Terraform. The AWS and Terraform paths ultimately produce the same runtime configuration this path has you write by hand.

Prerequisites​

  • Docker Engine + Docker Compose v2 on the host.
  • Network reachability to pull the container images (or a private mirror).

1. Runtime configuration​

The compose files read the environment file from the repo root, not from the deploy/ directory. Create both files there, and run every compose command from the repo root:

cp deploy/.env.example         .env
cp .env.provider-keys.example  .env.provider-keys   # optional model provider keys

Fill in every value in .env; there's no script here to derive anything for you:

  • Images: pin a real release tag.
  • Secrets: generate strong values with openssl rand -hex 32.
  • Datastore URLs: keep the compose service names as hosts unless you're pointing at external datastores.
  • Topology: INSTALL_TOPOLOGY=single is the whole story for one box; multi-node installs set GATEWAYS_PER_NODE / GATEWAY_SPECS.

Model-provider API keys go only in .env.provider-keys. They load into the gateway layer only, never into the platform services that store your data.

2. Bring the platform up​

Core services (Postgres, Redis, ClickHouse, the management backend, the web app, Prometheus, OTEL):

docker compose --env-file .env -f deploy/docker-compose.aws-core.yml up -d

Add the roles you need:

# gateways (single-node: same host; multi-node: run on each gateway host)
docker compose --env-file .env \
  -f deploy/docker-compose.aws-core.yml \
  -f deploy/docker-compose.aws-gateway.yml up -d

# front load balancer (optional)
docker compose --env-file .env \
  -f deploy/docker-compose.aws-core.yml \
  -f deploy/docker-compose.aws-lb.yml up -d

The database sets itself up on boot. There's no separate migration step.

3. Verify​

curl -f http://localhost:8001/api/v1/health     # management backend
curl -f http://localhost/                        # web app

Open the app at http://<host> (or your configured app origin).

Already have a cloud instance?​

  • Any Docker host you manage yourself (on-prem, another cloud, your own VM): this guide is the whole story.
  • An existing AWS EC2 you'd rather keep managing with the scripts: point the AWS install scripts at your existing instance ID and they adopt it instead of launching a new one, with no hand-filled .env.