Docker Compose Profiles Reference

This document explains the Docker Compose profile system for TradePsykl and how to use it for different development scenarios.

Default Development Setup

By default, .env configures:

COMPOSE_PROFILES=web,observability

Starting the default dev environment:

docker compose up -d

Result:

• ✅ API (port 8000)
• ✅ UI (port 5173)
• ✅ CMS (port 8080)
• ✅ Data/MongoDB (port 27017)
• ✅ Prometheus (port 9090) - Scraping metrics → Grafana Cloud Mimir
• ✅ Promtail (port 9080) - Shipping logs → Grafana Cloud Loki
• ❌ Engine (not started - use engine profile explicitly)

Available Profiles

Core Application Profiles

Profile	Services Started	Use Case
web	api, ui, cms, data	Frontend + API development
api	api, data	Backend API development only
engine	engine, data	Worker/strategy development
data	data	Database only (testing)

Infrastructure Profiles

Profile	Services Started	Use Case
observability	prometheus, promtail	Metrics & log shipping to Grafana Cloud
all	Everything	Full stack development

Common Development Scenarios

1. Frontend Development (Default)

Use case: Working on UI, CMS, or API endpoints

docker compose up -d
# Starts: web + observability

Services running:

• UI at http://localhost:5173
• API at http://localhost:8000
• CMS at http://localhost:8080
• MongoDB at localhost:27017
• Prometheus at http://localhost:9090
• Full telemetry flowing to Grafana Cloud

2. Backend API Development

Use case: Working on API endpoints, no frontend needed

COMPOSE_PROFILES=api,observability docker compose up -d

Services running:

• API at http://localhost:8000
• MongoDB at localhost:27017
• Prometheus + Promtail (observability)

3. Strategy/Engine Development

Use case: Working on trading strategies, signals, workers

COMPOSE_PROFILES=engine,observability docker compose up -d

Services running:

• Engine (worker process)
• MongoDB at localhost:27017
• Prometheus + Promtail (observability)

Note: Engine uses port 8080 for /metrics and /health endpoints. If you need both Engine and CMS, see "Combined Profiles" below.

4. Full Stack (All Services)

Use case: Integration testing, full system development

COMPOSE_PROFILES=all docker compose up -d

Services running:

• Everything: API, Engine, UI, CMS, Data, Prometheus, Promtail

Port conflict resolution: Engine and CMS both use port 8080. With all profile, you may need to temporarily change one port in docker-compose.yml.

5. Minimal (No Observability)

Use case: Quick iteration, resource-constrained environments, focused debugging

COMPOSE_PROFILES=web docker compose up -d

Services running:

• UI, API, CMS, Data only
• No local Prometheus or Promtail
• Traces still work (direct OTLP → Grafana Cloud)
• Metrics exposed but not scraped
• Logs not shipped to Loki

Note: Not recommended for normal development as it doesn't match production architecture.

Combined Profiles

You can combine multiple profiles:

# API + Engine + Observability
COMPOSE_PROFILES=api,engine,observability docker compose up -d

# Web + Engine (will have port conflict on 8080 - resolve first)
COMPOSE_PROFILES=web,engine,observability docker compose up -d

Observability-First Philosophy

Why observability is default:

• ✅ Matches production architecture
• ✅ Catches telemetry issues immediately
• ✅ Developers see metrics/logs/traces while coding
• ✅ Enables debugging with full context
• ✅ Minimal overhead (Prometheus + Promtail are lightweight)

What you get with observability profile:

• Metrics → Scraped by Prometheus → Remote Write to Grafana Cloud Mimir
• Traces → OTLP directly to Grafana Cloud Tempo
• Logs → Collected by Promtail → Grafana Cloud Loki
• Dashboards → Real-time visibility in Grafana Cloud

Troubleshooting

Services not starting?

# Check which services are configured
docker compose config --services

# Check which profiles are active
echo $COMPOSE_PROFILES

# View current service status
docker compose ps

Port conflicts?

Common port allocations:

• 5173: UI (Vite dev server)
• 8000: API (FastAPI)
• 8080: CMS (VuePress) OR Engine (/metrics endpoint)
• 9080: Promtail
• 9090: Prometheus
• 27017: MongoDB

Engine + CMS conflict: Both use 8080. Choose one or temporarily change port mapping.

Want to start a specific service manually?

# Start engine even though it's not in default profile
docker compose up -d engine

Observability overhead too much?

# Temporarily disable
COMPOSE_PROFILES=web docker compose up -d

# Or update .env permanently
COMPOSE_PROFILES=web

Environment Variables

Edit .env to change default behavior:

# Default profiles (change as needed)
COMPOSE_PROFILES=web,observability

# Other observability settings
DEPLOYMENT_ENVIRONMENT=dev
GRAFANA_PROM_USERNAME=<your_instance_id>
GRAFANA_LOKI_USERNAME=<your_instance_id>
# ... (see .env for full list)

Best Practices

1. Keep observability enabled unless you have a specific reason not to
2. Use profile combinations instead of all to avoid port conflicts
3. Document custom profiles in your feature branch if you create new ones
4. Test with observability before pushing to ensure telemetry works
5. Check Grafana Cloud regularly to verify metrics/logs/traces flowing

See Also

• docs/devops/observability.md - Observability architecture and design
• .github/copilot-instructions.md - Observability-first development guidance
• docs/GETTING-STARTED.md - General development setup