Docker Compose Setup

OneGlance uses Docker Compose to orchestrate multiple services including databases, cache, queue workers, and web applications. This guide explains the complete Docker Compose setup.

Architecture Overview

The Docker Compose configuration defines 9 services across 3 networks:

Data Services

PostgreSQL, ClickHouse, Redis

Applications

Web, Landing, Docs

Workers

Agent Worker, Migrations

Network Architecture

Services

PostgreSQL (db)

Main application database for storing users, workspaces, prompts, and configuration.

Image

string

ghcr.io/${GHCR_USERNAME}/oneglanse-postgres:latestCustom PostgreSQL image with initialization scripts.

Container Name

string

postgres_db

Volumes

array

db_data:/var/lib/postgresql/data - Persistent database storage
./packages/db/init-scripts:/docker-entrypoint-initdb.d - Initialization SQL scripts

Networks

array

data - Internal data network

Health Check

object

test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
interval: 5s
timeout: 5s
retries: 5

Checks database readiness before dependent services start.

Resource Limits

object

limits:
  cpus: '1'
  memory: 1G
reservations:
  cpus: '0.25'
  memory: 256M

Required Environment Variables:

POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_DB

Connection String:

DATABASE_URL=postgresql://user:password@db:5432/mydb

ClickHouse (clickhouse)

Analytics database for storing prompt responses, metrics, and time-series data.

Image

string

clickhouse/clickhouse-server:latestOfficial ClickHouse server image.

Container Name

string

clickhouse_db

Ports

array

No external ports exposed (internal access only via HTTP on port 8123).

Volumes

array

clickhouse_data:/var/lib/clickhouse - Persistent analytics data
./packages/db/clickhouse-init:/docker-entrypoint-initdb.d - Initialization scripts

Networks

array

data - Internal data network

Health Check

object

test: ["CMD-SHELL", "clickhouse-client --user ${CLICKHOUSE_USER} --password ${CLICKHOUSE_PASSWORD} --query 'SELECT 1'"]
interval: 10s
timeout: 5s
retries: 5
start_period: 60s

Longer start period (60s) allows ClickHouse initialization to complete.

Resource Limits

object

limits:
  cpus: '2'
  memory: 2G
reservations:
  cpus: '0.5'
  memory: 512M

Required Environment Variables:

CLICKHOUSE_USER
CLICKHOUSE_PASSWORD
CLICKHOUSE_DB

Connection URL:

CLICKHOUSE_URL=http://clickhouse:8123

Redis (redis)

In-memory data store for BullMQ job queues and application caching.

Image

string

redis:7-alpineLightweight Redis 7 image.

Container Name

string

redis

Command

string

redis-server --requirepass ${REDIS_PASSWORD}

Starts Redis with password authentication enabled.

Volumes

array

redis_data:/data - Persistent cache and queue data

Networks

array

data - Internal data network

Health Check

object

test: ["CMD-SHELL", "redis-cli -a \"${REDIS_PASSWORD}\" --no-auth-warning ping"]
interval: 5s
timeout: 3s
retries: 5

Resource Limits

object

limits:
  cpus: '0.5'
  memory: 512M
reservations:
  cpus: '0.1'
  memory: 128M

Required Environment Variables:

REDIS_PASSWORD

Connection URL:

REDIS_URL=redis://:password@redis:6379

Redis requires password authentication. Ensure REDIS_PASSWORD is set in .env and matches in apps/agent/.env.

Web App (web)

Main authenticated product application (Next.js 15 + tRPC).

Image

string

ghcr.io/${GHCR_USERNAME}/oneglanse-web:latest

Container Name

string

oneglanse-web

Ports

array

127.0.0.1:3001:3000 - Web interface bound to localhost only

Networks

array

frontend - Public-facing network
backend - Internal backend communication
data - Database access

Environment

object

HOSTNAME: 0.0.0.0
PORT: "3000"

Plus all variables from .env.

Dependencies

array

Waits for:

db (healthy)
migrate (completed successfully)
redis (healthy)
clickhouse (healthy)

Resource Limits

object

limits:
  cpus: '1'
  memory: 1G
reservations:
  cpus: '0.25'
  memory: 256M

Access: http://localhost:3001

Landing App (landing)

Public marketing website.

Image

string

ghcr.io/${GHCR_USERNAME}/oneglanse-landing:latest

Container Name

string

oneglanse-landing

Ports

array

127.0.0.1:3000:3000 - Public website bound to localhost

Networks

array

frontend - Public-facing network only

Environment

object

HOSTNAME: 0.0.0.0
PORT: "3000"

Resource Limits

object

limits:
  cpus: '0.5'
  memory: 512M
reservations:
  cpus: '0.1'
  memory: 128M

Access: http://localhost:3000

Docs App (docs)

Public technical documentation site.

Image

string

ghcr.io/${GHCR_USERNAME}/oneglanse-docs:latest

Container Name

string

oneglanse-docs

Ports

array

127.0.0.1:3002:3002 - Documentation site bound to localhost

Networks

array

frontend - Public-facing network only

Environment

object

HOSTNAME: 0.0.0.0
PORT: "3002"

Resource Limits

object

limits:
  cpus: '0.5'
  memory: 512M
reservations:
  cpus: '0.1'
  memory: 128M

Access: http://localhost:3002

Agent Worker (agent-worker)

BullMQ worker that processes browser automation jobs using Playwright.

Image

string

ghcr.io/${GHCR_USERNAME}/oneglanse-agent:latest

Container Name

string

oneglanse-agent-worker

Command

string

pnpm start:worker

Shared Memory

string

1gbRequired for Chromium browser instances.

Stop Grace Period

string

16mAllows long-running browser jobs to complete gracefully before shutdown.

Volumes

array

agent_storage:/storage - Browser profiles and session data

Networks

array

backend - Communication with web app
data - Redis queue access

Environment Files

array

.env - Shared environment variables
apps/agent/.env - Agent-specific configuration

Dependencies

array

Waits for:

redis (healthy)

Health Check

object

test: ["CMD", "node", "-e", "require('ioredis').default({host:'redis'}).ping().then(()=>process.exit(0)).catch(()=>process.exit(1))"]
interval: 15s
timeout: 10s
retries: 3
start_period: 20s

Verifies Redis connectivity.

Resource Limits

object

limits:
  cpus: '2'
  memory: 4G
reservations:
  cpus: '1'
  memory: 1G

Higher resources for browser automation.

The agent worker requires significant resources for browser instances. Adjust AGENT_WORKER_CONCURRENCY based on available CPU/memory.

Database Migrations (migrate)

One-shot service that runs Drizzle ORM migrations on startup.

Image

string

ghcr.io/${GHCR_USERNAME}/oneglanse-web:latestUses web image which contains the @oneglanse/db package.

Container Name

string

oneglanse-migrate

Command

string

pnpm --filter @oneglanse/db db:migrate

Restart Policy

string

noRuns once and exits.

Networks

array

data - Database access

Dependencies

array

Waits for:

db (healthy)

Volumes

Persistent storage volumes for stateful services:

db_data

volume

PostgreSQL database files. Contains all application data including users, workspaces, prompts.Location: /var/lib/postgresql/data in container

clickhouse_data

volume

ClickHouse database files. Contains analytics data, prompt responses, metrics.Location: /var/lib/clickhouse in container

redis_data

volume

Redis persistence files. Contains job queues and cache data.Location: /data in container

agent_storage

volume

Agent worker storage. Contains browser profiles, authentication data, temporary files.Location: /storage in container

Deleting volumes will permanently destroy data. Use docker compose down -v with caution.

Networks

Three isolated networks for security and organization:

frontend

bridge

Purpose: Public-facing applicationsServices: Landing, Docs, WebApplications that serve HTTP traffic to users.

backend

bridge

Purpose: Internal service communicationServices: Web, Agent WorkerServices that communicate internally but don’t need database access.

data

bridge

Purpose: Database and cache accessServices: DB, ClickHouse, Redis, Web, Agent Worker, MigrateServices that require direct database or cache connectivity.

Common Commands

Starting Services

docker compose up -d

Stopping Services

docker compose down

Viewing Logs

docker compose logs -f

Service Management

docker compose ps

Health Checks

docker compose ps

Port Mappings

Services accessible from the host machine:

Service	Container Port	Host Port	URL
Web App	3000	3001	http://localhost:3001
Landing	3000	3000	http://localhost:3000
Docs	3002	3002	http://localhost:3002
PostgreSQL	5432	Not exposed	Internal only
ClickHouse	8123	Not exposed	Internal only
Redis	6379	Not exposed	Internal only

Database services are not exposed to the host for security. Use docker compose exec to access them directly.

Resource Management

Total resource allocation when all services are running:

CPU

limits

Maximum: 7.5 CPUs Reserved: 2.85 CPUs

Memory

limits

Maximum: 9.5 GB Reserved: 2.6 GB

Adjusting Resources

Modify resource limits in docker-compose.yml:

agent-worker:
  deploy:
    resources:
      limits:
        cpus: '4'  # Increase for more concurrent jobs
        memory: 8G
      reservations:
        cpus: '2'
        memory: 2G

Troubleshooting

Services won't start

Problem: Services fail to start or remain unhealthy.Solutions:

Check service logs:
```
docker compose logs <service-name>
```
Verify environment variables:
```
docker compose config
```
Ensure GHCR_USERNAME is set:
```
echo $GHCR_USERNAME
```
Check Docker resources in Docker Desktop settings

Reset everything:

docker compose down -v
docker compose up -d

Port already in use

Problem: Port binding errors on startup.Solutions:

Find process using the port:

lsof -i :3000
lsof -i :3001
lsof -i :3002

Stop conflicting service or change port in docker-compose.yml:

ports:
  - "127.0.0.1:3003:3000"  # Use port 3003 instead

Database connection errors

Problem: Applications can’t connect to databases.Solutions:

Verify database is healthy:
```
docker compose ps db
```

Check DATABASE_URL uses service name:

DATABASE_URL=postgresql://user:password@db:5432/mydb

Test connection:

docker compose exec web sh -c 'ping -c 1 db'

Verify credentials match:

docker compose exec db psql -U $POSTGRES_USER -d $POSTGRES_DB

Migration fails

Problem: migrate service fails or exits with error.Solutions:

Check migration logs:
```
docker compose logs migrate
```
Ensure database is ready:
```
docker compose ps db
```
Run manually:
```
docker compose run --rm migrate
```

Reset database (development only):

docker compose down -v
docker compose up -d db
docker compose run --rm migrate

Agent worker not processing jobs

Problem: Jobs queue but aren’t executed.Solutions:

Check agent worker logs:
```
docker compose logs -f agent-worker
```

Verify Redis connectivity:

docker compose exec agent-worker sh -c 'ping -c 1 redis'

Check Redis password matches in .env and apps/agent/.env
Restart worker:
```
docker compose restart agent-worker
```
Increase worker concurrency in .env:
```
AGENT_WORKER_CONCURRENCY=2
```

Out of memory errors

Problem: Services crash with OOM errors.Solutions:

Increase Docker memory limit in Docker Desktop
Reduce agent worker concurrency:
```
AGENT_WORKER_CONCURRENCY=1
```
Adjust memory limits in docker-compose.yml
Monitor resource usage:
```
docker stats
```

Image pull failures

Problem: Can’t pull Docker images from GHCR.Solutions:

Verify GHCR_USERNAME is set:
```
echo $GHCR_USERNAME
```

Authenticate with GHCR:

echo $GITHUB_TOKEN | docker login ghcr.io -u $GHCR_USERNAME --password-stdin

Check image exists:

docker pull ghcr.io/$GHCR_USERNAME/oneglanse-web:latest

For private repos, ensure GitHub token has read:packages scope

Production Considerations

Additional configuration required for production deployments:

Use External Databases
- Managed PostgreSQL (RDS, Cloud SQL)
- Managed Redis (ElastiCache, Redis Cloud)
- Managed ClickHouse (ClickHouse Cloud)
Configure Reverse Proxy
- Use nginx or Traefik in front of services
- Configure SSL/TLS certificates
- Set up domain routing
Enable Monitoring
- Add Prometheus for metrics
- Configure logging aggregation
- Set up health check endpoints
Secrets Management
- Use Docker secrets or external secret managers
- Never commit .env with production credentials
- Rotate secrets regularly
Backup Strategy
- Automate volume backups
- Test restore procedures
- Document backup retention policy
Security Hardening
- Run containers as non-root users
- Enable Docker Content Trust
- Scan images for vulnerabilities
- Use private networks

Next Steps

Local Setup

Complete local development setup guide

Environment Variables

Learn about all environment variables

Architecture

Understand the system architecture

Deployment

Deploy to production

Architecture

Setup & Deployment

Components

Contributing

Docker Compose Setup

Architecture Overview

Data Services

Applications

Workers

Network Architecture

Services

PostgreSQL (db)

ClickHouse (clickhouse)

Redis (redis)

Web App (web)

Landing App (landing)

Docs App (docs)

Agent Worker (agent-worker)

Database Migrations (migrate)

Volumes

Networks

Common Commands

Starting Services

Stopping Services

Viewing Logs

Service Management

Health Checks

Port Mappings

Resource Management

Adjusting Resources

Troubleshooting

Production Considerations

Next Steps

Local Setup

Environment Variables

Architecture

Deployment

Build docs developers (and LLMs) love

Architecture

Setup & Deployment

Components

Contributing

​Architecture Overview

Data Services

Applications

Workers

​Network Architecture

​Services

​PostgreSQL (db)

​ClickHouse (clickhouse)

​Redis (redis)

​Web App (web)

​Landing App (landing)

​Docs App (docs)

​Agent Worker (agent-worker)

​Database Migrations (migrate)

​Volumes

​Networks

​Common Commands

​Starting Services

​Stopping Services

​Viewing Logs

​Service Management

​Health Checks

​Port Mappings

​Resource Management

​Adjusting Resources

​Troubleshooting

​Production Considerations

​Next Steps

Local Setup

Environment Variables

Architecture

Deployment

Build docs developers (and LLMs) love

Architecture Overview

Network Architecture

Services

PostgreSQL (db)

ClickHouse (clickhouse)

Redis (redis)

Web App (web)

Landing App (landing)

Docs App (docs)

Agent Worker (agent-worker)

Database Migrations (migrate)

Volumes

Networks

Common Commands

Starting Services

Stopping Services

Viewing Logs

Service Management

Health Checks

Port Mappings

Resource Management

Adjusting Resources

Troubleshooting

Production Considerations

Next Steps