Skip to main content

​
Overview

The BE Monorepo uses Docker Compose to manage development infrastructure services including PostgreSQL, Redis, and OpenTelemetry observability stack.

​
Docker Compose Configuration

The Docker setup is located in the docker/ directory and includes three core services:

​
Services

​
PostgreSQL Database

PostgreSQL 17 is used as the primary database: 
postgres_db:
  image: postgres:17
  environment:
    POSTGRES_DB: postgres_db
    POSTGRES_USER: postgres_db
    POSTGRES_PASSWORD: postgres_db
  ports:
    - "5432:5432"
  volumes:
    - postgres_db_data:/var/lib/postgresql/data
  restart: unless-stopped
Connection String: 
postgres://postgres_db:postgres_db@localhost:5432/postgres_db

​
Redis Cache

Redis is used for caching and session management: 
redis_cache:
  image: redis:latest
  ports:
    - "6379:6379"
  volumes:
    - redis_cache_data:/data
  restart: unless-stopped

​
Grafana LGTM Stack (Observability)

Integrated Loki, Grafana, Tempo, and Mimir (LGTM) stack for observability: 
otel_lgtm:
  image: docker.io/grafana/otel-lgtm:latest
  ports:
    - "3111:3000" # Grafana UI
    - "4317:4317" # OTLP gRPC receiver
    - "4318:4318" # OTLP http receiver
  volumes:
    - ./container/grafana:/data/grafana
    - ./container/prometheus:/data/prometheus
    - ./container/loki:/data/loki
  environment:
    - GF_PATHS_DATA=/data/grafana
  env_file:
    - ./.env
Access Grafana: http://localhost:3111

​
Data Persistence

Docker volumes ensure data persistence across container restarts: 
volumes:
  postgres_db_data:
  redis_cache_data:

​
Starting Services

​
Using npm/bun Scripts

The recommended way to start all services: 
bun compose:up
This command is defined in the root package.json: 
"compose:up": "docker compose -f ./docker/docker-compose.yml up --build"

​
Manual Docker Compose

You can also run Docker Compose manually: 
# Start all services
docker compose -f ./docker/docker-compose.yml up

# Start in detached mode
docker compose -f ./docker/docker-compose.yml up -d

# Rebuild and start
docker compose -f ./docker/docker-compose.yml up --build

# Stop all services
docker compose -f ./docker/docker-compose.yml down

# Stop and remove volumes
docker compose -f ./docker/docker-compose.yml down -v

​
Environment Configuration

Create a .env file in the docker/ directory for the observability stack. See .env.example for reference. For the Hono application, configure the database connection in apps/hono/.env.dev or apps/hono/.env.prod: 
DATABASE_URL="postgres://postgres_db:postgres_db@localhost:5432/postgres_db"

​
Service Health Checks

Verify services are running: 
# Check running containers
docker compose -f ./docker/docker-compose.yml ps

# View logs
docker compose -f ./docker/docker-compose.yml logs

# Follow logs for specific service
docker compose -f ./docker/docker-compose.yml logs -f postgres_db

​
Port Mapping

ServiceContainer PortHost PortPurpose
PostgreSQL54325432Database connection
Redis63796379Cache connection
Grafana30003111Observability UI
OTLP gRPC43174317OpenTelemetry gRPC
OTLP HTTP43184318OpenTelemetry HTTP

​
Troubleshooting

​
Port Conflicts

If ports are already in use, modify the port mappings in docker-compose.yml: 
ports:
  - "5433:5432"  # Use different host port

​
Volume Permissions

Ensure the container directories have proper permissions: 
mkdir -p docker/container/{grafana,prometheus,loki}
chmod -R 777 docker/container/

​
Reset Database

To completely reset the database: 
docker compose -f ./docker/docker-compose.yml down -v
docker compose -f ./docker/docker-compose.yml up

​
Production Considerations

The current Docker setup is designed for development. For production:
  • Use secure passwords and credentials
  • Configure proper networking and security groups
  • Set up automated backups for PostgreSQL
  • Use managed services for Redis and databases
  • Configure proper resource limits

​
Next Steps

Production Build

Learn about building the application for production

CI/CD

Set up continuous integration and deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us