Docker Deployment
Run Cogitator with Docker Compose — PostgreSQL, Redis, Ollama, and production container setup.
Infrastructure Services
The Cogitator repository ships a docker-compose.yml with the three services agents usually need: PostgreSQL with pgvector for memory storage, Redis for caching, distributed state and job queues, and Ollama for local LLM inference.
docker compose up -d
# or, from any directory below the compose file:
cogitator up # runs `docker compose up -d` when there is no assistant cogitator.yml here
cogitator down # `docker compose down`; add -v to delete the volumescogitator up starts an assistant when the current directory has an assistant cogitator.yml (a runtime config such as the one create-cogitator-app generates does not count); otherwise it looks for docker-compose.yml / compose.yml in the current directory and up to five parents and starts those services (--pull pulls images first, --no-detach runs in the foreground).
| Service | Image | Port | Purpose |
|---|---|---|---|
| PostgreSQL | pgvector/pgvector:pg16 | 5432 | Vector memory, agent state |
| Redis | redis:7-alpine | 6379 | Cache, events, job queues |
| Ollama | ollama/ollama:latest | 11434 | Local LLM runtime |
| ollama-init | ollama/ollama:latest | — | One-shot: pulls nomic-embed-text-v2-moe and llama3.2:3b |
Docker Compose Configuration
services:
postgres:
image: pgvector/pgvector:pg16
environment:
POSTGRES_USER: cogitator
POSTGRES_PASSWORD: cogitator_dev
POSTGRES_DB: cogitator
ports:
- '5432:5432'
volumes:
- postgres_data:/var/lib/postgresql/data
- ./docker/postgres/init.sql:/docker-entrypoint-initdb.d/init.sql:ro
healthcheck:
test: ['CMD-SHELL', 'pg_isready -U cogitator -d cogitator']
interval: 5s
timeout: 5s
retries: 5
restart: unless-stopped
redis:
image: redis:7-alpine
ports:
- '6379:6379'
volumes:
- redis_data:/data
command: redis-server --appendonly yes
healthcheck:
test: ['CMD', 'redis-cli', 'ping']
interval: 5s
timeout: 5s
retries: 5
restart: unless-stopped
ollama:
image: ollama/ollama:latest
ports:
- '11434:11434'
volumes:
- ollama_data:/root/.ollama
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
restart: unless-stopped
volumes:
postgres_data:
redis_data:
ollama_data:docker/postgres/init.sql enables the vector and uuid-ossp extensions on first start.
Environment Variables
Create a .env file in your project root:
DATABASE_URL=postgresql://cogitator:cogitator_dev@localhost:5432/cogitator
REDIS_URL=redis://localhost:6379
OLLAMA_URL=http://localhost:11434
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...@cogitator-ai/config maps OLLAMA_URL (or OLLAMA_HOST) and the provider API keys onto llm.providers automatically. DATABASE_URL and REDIS_URL are conventions for your own code — pass them to the memory adapters or Redis client you create (the cogitator init templates and the built-in sqlQuery tool read DATABASE_URL):
import { PostgresAdapter } from '@cogitator-ai/memory';
const memory = new PostgresAdapter({
provider: 'postgres',
connectionString: process.env.DATABASE_URL!,
});Production Dockerfile
cogitator deploy generates a Dockerfile, a Compose stack and preflight checks for you — see Deploy Package. If you maintain your own, a multi-stage build looks like this:
FROM node:22-alpine AS builder
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN corepack enable && pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
CMD wget --no-verbose --tries=1 --spider http://localhost:3000/cogitator/health || exit 1
CMD ["node", "dist/index.js"]The server adapters expose GET /health and GET /ready under their base path (/cogitator by default) — point the health check at whatever path you mounted them on.
GPU and CPU-Only Mode
The default compose file reserves NVIDIA GPUs for Ollama. On Apple Silicon, run Ollama natively:
brew install ollama && ollama serve
docker compose up -d postgres redisWithout a GPU, use the CPU compose variant (no GPU reservation; pulls nomic-embed-text instead of the MoE embedding model) and smaller models:
docker compose -f docker-compose.cpu.yml up -d
docker compose exec ollama ollama pull llama3.2:3bProduction Checklist
- External PostgreSQL with backups, connection pooling (PgBouncer), and pgvector
- Redis Cluster or managed Redis (ElastiCache, Upstash) for HA — see Redis
- Dedicated GPU server for Ollama, or cloud providers (OpenAI, Anthropic, Google)
- Reverse proxy (nginx, Caddy) with TLS termination
- Secrets management via Vault, AWS SSM, or Kubernetes secrets
- Health checks on all services to enable orchestrator restarts