Docker Compose

Docker Compose is the recommended deployment mode for development teams and self-hosted production environments. It starts PostgreSQL, Typesense, and the Open Astra gateway together as a coordinated stack.

Prerequisites

Docker Desktop 4.x or Docker Engine 24+ with Compose v2
At least one LLM provider API key
4 GB RAM available for the stack

Quick start

bash

# Download and enter the project directory
npx astra@latest init
cd astra

# Copy and edit the environment file
cp .env.example .env

# Start backing services only (recommended for development)
docker compose up -d postgres typesense

# Then run the gateway locally with hot-reload
npm install
npm run dev

To start the full stack including the gateway container:

bash

docker compose up -d

Environment file setup

Copy .env.example to .env and fill in the required values. The gateway container reads this file at startup.

bash

# Required — the gateway will not start without these
JWT_SECRET=change-me-to-a-long-random-string
TYPESENSE_API_KEY=change-me
INTERNAL_API_KEY=change-me

# PostgreSQL (matches docker-compose.yml defaults)
PG_HOST=postgres
PG_PORT=5432
PG_DATABASE=astra
PG_USER=astra
PG_PASSWORD=astra

# At least one provider key is required
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=...
# GROQ_API_KEY=gsk_...

⚠Never commit your .env file to version control. The .gitignore in the repository already excludes it.

Services

The docker-compose.yml defines three services:

Service	Image	Port	Purpose
`postgres`	postgres:17-alpine	5432	Primary database — sessions, memory, billing, migrations
`typesense`	typesense/typesense:27.1	8108	Hybrid BM25 + vector search for memory and knowledge
`gateway`	Built from Dockerfile	3000	Open Astra API server

Data volumes

Data is persisted in named Docker volumes so it survives container restarts and upgrades:

yaml

volumes:
  pg-data:          # PostgreSQL data directory
  typesense-data:   # Typesense data and index files

Development workflow

The recommended development workflow is to run only the backing services in Docker and the gateway locally, so you get fast hot-reload with tsx watch:

bash

# Terminal 1 — start backing services
docker compose up -d postgres typesense

# Terminal 2 — run gateway with hot-reload
npm run dev

# Check logs for any service
docker compose logs -f postgres
docker compose logs -f typesense

Production notes

Set NODE_ENV=production in your .env to enable production logging and disable verbose debug output
Use a managed PostgreSQL service (RDS, Cloud SQL, DigitalOcean Managed Postgres) in production — the Docker Postgres is fine for development
Place a reverse proxy (nginx, Caddy, Traefik) in front of the gateway for TLS termination and load balancing
Set resource limits on containers in production to prevent runaway memory usage

See Docker Deployment for a full production-grade setup with multi-stage builds and health checks.