Skip to main content
The development environment is optimized for local development and debugging. It builds all services from source and exposes ports for direct access to individual services.

​
Configuration Overview

The compose.dev.yaml configuration includes:
  • Local builds - Services are built from local source using the Dockerfile
  • All ports exposed - Direct access to databases and services for debugging
  • No resource limits - Services use available resources freely
  • Observability built-in - Grafana dashboard on port 3000
  • Hot reload support - Volume mounts for certificate sharing

​
Starting the Development Environment

1

Clone the Repository

git clone https://github.com/your-org/chronoverse.git
cd chronoverse
2

Start All Services

Start the entire stack with automatic certificate generation:
docker compose -f compose.dev.yaml up -d
The first startup will take several minutes as it builds all service images and generates TLS certificates.
3

Verify Services

Check that all services are running and healthy:
docker compose -f compose.dev.yaml ps
All services should show status healthy or running.
4

Access the Dashboard

Open your browser and navigate to:

​
Exposed Ports

The development environment exposes the following ports on localhost:
ServicePortPurpose
PostgreSQL5432Database access
ClickHouse9440Analytics database (TLS)
Redis6379Cache (TLS)
Kafka9094, 9093Event streaming (SSL)
Meilisearch7700Search engine (HTTPS)
Grafana/LGTM3000, 4317Observability
users-service50051User management (gRPC/TLS)
workflows-service50052Workflow orchestration (gRPC/TLS)
jobs-service50053Job management (gRPC/TLS)
notifications-service50054Notifications (gRPC/TLS)
analytics-service50055Analytics (gRPC/TLS)
server8080REST API gateway
dashboard3001Web interface

​
Working with the Development Environment

​
Viewing Logs

# Follow all service logs
docker compose -f compose.dev.yaml logs -f

​
Rebuilding Services

After making code changes, rebuild and restart services: 
# Rebuild all services
docker compose -f compose.dev.yaml build

# Rebuild specific service
docker compose -f compose.dev.yaml build users-service

# Rebuild and restart
docker compose -f compose.dev.yaml up -d --build

​
Restarting Services

# Restart all services
docker compose -f compose.dev.yaml restart

# Restart specific service
docker compose -f compose.dev.yaml restart users-service

​
Stopping the Environment

# Stop services but keep volumes
docker compose -f compose.dev.yaml down
Using down -v will delete all data including databases and certificates. Only use this for a complete reset.

​
Certificate Management

The init-certs service automatically generates TLS certificates on first startup:
  • CA Certificate - Root certificate authority
  • Service Certificates - Individual certs for each service
  • Client Certificates - Client certificates for mTLS authentication
  • Auth Keypair - ED25519 keypair for JWT signing
Certificates are stored in ./certs/ and mounted as read-only volumes.

​
Regenerating Certificates

If you need to regenerate certificates: 
# Stop services
docker compose -f compose.dev.yaml down

# Remove certificate directory
rm -rf certs/

# Start services (will regenerate)
docker compose -f compose.dev.yaml up -d

​
Database Access

​
PostgreSQL

Connect to PostgreSQL with TLS: 
# Using psql with client certificates
psql "host=localhost port=5432 user=primary dbname=chronoverse \
  sslmode=verify-full \
  sslrootcert=certs/ca/ca.crt \
  sslcert=certs/clients/client.crt \
  sslkey=certs/clients/client.key"

​
ClickHouse

Connect to ClickHouse: 
# Using clickhouse-client
docker exec -it clickhouse clickhouse-client \
  --secure \
  --host=localhost \
  --port=9440 \
  --user=chronoverse-client \
  --password=chronoverse

​
Redis

Connect to Redis with TLS: 
# Using redis-cli
docker exec -it redis redis-cli \
  --tls \
  --cert /certs/clients/client.crt \
  --key /certs/clients/client.key \
  --cacert /certs/ca/ca.crt \
  -p 6379

​
Health Checks

All services implement health checks: 
# Check service health
docker compose -f compose.dev.yaml ps

# Detailed health status
docker inspect --format='{{.State.Health.Status}}' users-service

# View health check logs
docker inspect --format='{{range .State.Health.Log}}{{.Output}}{{end}}' users-service

​
Observability

The development environment includes the LGTM stack (Loki, Grafana, Tempo, Mimir): All services export telemetry to the LGTM stack via OTLP/gRPC.

​
Troubleshooting

​
Services Not Starting

Check service dependencies and health: 
# View service status
docker compose -f compose.dev.yaml ps

# Check specific service logs
docker compose -f compose.dev.yaml logs users-service

​
Certificate Errors

If you see certificate-related errors: 
# Verify certificates were generated
ls -la certs/

# Check init-certs logs
docker compose -f compose.dev.yaml logs init-certs

# Regenerate if needed (see Certificate Management above)

​
Port Conflicts

If ports are already in use: 
# Find what's using a port
sudo lsof -i :5432

# Stop conflicting service or modify compose file

​
Database Connection Issues

Verify database services are healthy: 
# Check database health
docker compose -f compose.dev.yaml ps postgres clickhouse redis

# View database logs
docker compose -f compose.dev.yaml logs postgres

​
Development Workflow

  1. Make Code Changes - Edit source files in your IDE
  2. Rebuild Service - docker compose -f compose.dev.yaml build <service>
  3. Restart Service - docker compose -f compose.dev.yaml up -d <service>
  4. View Logs - docker compose -f compose.dev.yaml logs -f <service>
  5. Test Changes - Access service via exposed port

​
Next Steps

Configuration Reference

Detailed environment variable reference

API Documentation

Explore the REST API

Observability

Monitor your services with Grafana

Production Deployment

Deploy to production when ready

Build docs developers (and LLMs) love

Get started for freeTalk to us