Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aryamantodkar/oneglanse/llms.txt

Use this file to discover all available pages before exploring further.

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:
ServiceContainer PortHost PortURL
Web App30003001http://localhost:3001
Landing30003000http://localhost:3000
Docs30023002http://localhost:3002
PostgreSQL5432Not exposedInternal only
ClickHouse8123Not exposedInternal only
Redis6379Not exposedInternal 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

Problem: Services fail to start or remain unhealthy.Solutions:
  1. Check service logs: 
    docker compose logs <service-name>
  2. Verify environment variables: 
    docker compose config
  3. Ensure GHCR_USERNAME is set: 
    echo $GHCR_USERNAME
  4. Check Docker resources in Docker Desktop settings
  5. Reset everything: 
    docker compose down -v
docker compose up -d
Problem: Port binding errors on startup.Solutions:
  1. Find process using the port: 
    lsof -i :3000
lsof -i :3001
lsof -i :3002
  2. Stop conflicting service or change port in docker-compose.yml: 
    ports:
  - "127.0.0.1:3003:3000"  # Use port 3003 instead
Problem: Applications can’t connect to databases.Solutions:
  1. Verify database is healthy: 
    docker compose ps db
  2. Check DATABASE_URL uses service name: 
    DATABASE_URL=postgresql://user:password@db:5432/mydb
  3. Test connection: 
    docker compose exec web sh -c 'ping -c 1 db'
  4. Verify credentials match: 
    docker compose exec db psql -U $POSTGRES_USER -d $POSTGRES_DB
Problem: migrate service fails or exits with error.Solutions:
  1. Check migration logs: 
    docker compose logs migrate
  2. Ensure database is ready: 
    docker compose ps db
  3. Run manually: 
    docker compose run --rm migrate
  4. Reset database (development only): 
    docker compose down -v
docker compose up -d db
docker compose run --rm migrate
Problem: Jobs queue but aren’t executed.Solutions:
  1. Check agent worker logs: 
    docker compose logs -f agent-worker
  2. Verify Redis connectivity: 
    docker compose exec agent-worker sh -c 'ping -c 1 redis'
  3. Check Redis password matches in .env and apps/agent/.env
  4. Restart worker: 
    docker compose restart agent-worker
  5. Increase worker concurrency in .env: 
    AGENT_WORKER_CONCURRENCY=2
Problem: Services crash with OOM errors.Solutions:
  1. Increase Docker memory limit in Docker Desktop
  2. Reduce agent worker concurrency: 
    AGENT_WORKER_CONCURRENCY=1
  3. Adjust memory limits in docker-compose.yml
  4. Monitor resource usage: 
    docker stats
Problem: Can’t pull Docker images from GHCR.Solutions:
  1. Verify GHCR_USERNAME is set: 
    echo $GHCR_USERNAME
  2. Authenticate with GHCR: 
    echo $GITHUB_TOKEN | docker login ghcr.io -u $GHCR_USERNAME --password-stdin
  3. Check image exists: 
    docker pull ghcr.io/$GHCR_USERNAME/oneglanse-web:latest
  4. For private repos, ensure GitHub token has read:packages scope

​
Production Considerations

Additional configuration required for production deployments:
  1. Use External Databases
    • Managed PostgreSQL (RDS, Cloud SQL)
    • Managed Redis (ElastiCache, Redis Cloud)
    • Managed ClickHouse (ClickHouse Cloud)
  2. Configure Reverse Proxy
    • Use nginx or Traefik in front of services
    • Configure SSL/TLS certificates
    • Set up domain routing
  3. Enable Monitoring
    • Add Prometheus for metrics
    • Configure logging aggregation
    • Set up health check endpoints
  4. Secrets Management
    • Use Docker secrets or external secret managers
    • Never commit .env with production credentials
    • Rotate secrets regularly
  5. Backup Strategy
    • Automate volume backups
    • Test restore procedures
    • Document backup retention policy
  6. 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

Build docs developers (and LLMs) love

Get started for freeTalk to us