Skip to content

Docker Setup and Healthchecks

Services Overview

  • PostgreSQL with TimescaleDB (port 5432) - Time-series database
  • Redis (port 6379) - Caching layer
  • ChromaDB (port 8000) - Vector memory storage
  • Maricusco application - Main framework
  • Prometheus (port 9090) - Metrics collection and UI
  • Grafana (port 3000) - Metrics visualization and dashboards

Grafana Service

Configuration

  • Image: grafana/grafana:12.3.0 (pinned stable version)
  • Container: maricusco-grafana
  • Port: 3000 (configurable via GRAFANA_PORT environment variable)
  • Access URL: http://localhost:3000

Environment Variables

  • GF_SECURITY_ADMIN_USER: Grafana admin username (defaults to admin if not set)
  • GF_SECURITY_ADMIN_PASSWORD: Grafana admin password (defaults to admin for local development if not set)
  • Important: For non-local/production environments, GF_SECURITY_ADMIN_PASSWORD must be set to a secure password via .env file
  • For local development, default credentials are admin / admin when not set (convenient for development, not secure for production)
  • Note: Grafana uses GF_ prefix for all configuration environment variables

Accessing Grafana UI

  1. Start Grafana service: docker-compose up -d grafana (or docker-compose up -d for all services)
  2. Open browser: Navigate to http://localhost:3000
  3. Login:
  4. Local development: Default credentials are admin / admin (when GF_SECURITY_ADMIN_PASSWORD is not set in .env)
  5. Production/non-local: Use credentials from .env file (GF_SECURITY_ADMIN_USER / GF_SECURITY_ADMIN_PASSWORD)
  6. Navigate to dashboards: Click "Dashboards" → "Maricusco" folder to see pre-provisioned dashboards
  7. Verify metrics: Ensure MARICUSCO_METRICS_ENABLED=true for metrics to appear in dashboards

Pre-Provisioned Components

  • Data Source: Prometheus data source automatically configured (no manual setup required)
  • Dashboards: Three starter dashboards pre-provisioned:
  • Maricusco Overview (comprehensive system metrics)
  • Maricusco Vendor/Operation Latency (detailed latency breakdowns)
  • Maricusco Cache Performance (cache-specific metrics)
  • All dashboards are organized in the "Maricusco" folder in Grafana UI

Persistent Storage

  • Grafana data (dashboards, users, preferences) stored in grafana_data volume
  • Data persists across container restarts
  • Provisioning configs mounted read-only from docker/grafana/provisioning/

Healthcheck Configuration (docker-compose)

  • App healthcheck: HTTP GET http://localhost:8000/health via curl (fallback wget).
  • Timing: interval 30s, timeout 2s, retries 3, start_period 40s.
  • Defined in docker-compose.yml under the app service.
  • Expectations:
  • Returns 200 when required dependencies are healthy.
  • Returns 503 when any required dependency (PostgreSQL, Redis) is unhealthy.

Healthcheck Configuration (Dockerfile)

  • Runtime HEALTHCHECK mirrors compose settings: interval 30s, timeout 2s, retries 3, start_period 40s.
  • Uses curl against http://localhost:8000/health.
  • Runtime app: uvicorn maricusco.api.app:app --host 0.0.0.0 --port 8000 (unified health + metrics).

Verifying Health

  • Container status: docker-compose ps (shows healthy/unhealthy).
  • Direct probe: docker exec maricusco-app curl -i http://localhost:8000/health.
  • Startup period: during start_period the container may show starting; it should transition to healthy once dependencies are reachable and the endpoint responds 200.

Troubleshooting Healthcheck Failures

  • Check logs: docker-compose logs app | tail -n 100.
  • Inspect dependencies:
  • PostgreSQL: docker-compose ps postgres; logs with docker-compose logs postgres.
  • Redis: docker-compose ps redis; logs with docker-compose logs redis.
  • Manual probes:
  • Postgres connectivity from app: docker exec maricusco-app pg_isready -h postgres -p 5432 -U ${POSTGRES_USER:-maricusco} (if client installed).
  • Redis connectivity from app: docker exec maricusco-app redis-cli -h redis -p 6379 ping (if client installed).
  • Verify config:
  • Ensure MARICUSCO_HEALTHCHECK_ENABLED=true (default) and endpoint path matches healthcheck URL.
  • Confirm timeouts are not set too low for your environment (MARICUSCO_HEALTHCHECK_TIMEOUT_DEFAULT, per-dependency overrides).
  • If health remains unhealthy:
  • Curl the endpoint and inspect errors in the JSON response to see which dependency failed.
  • Ensure uvicorn is running and listening on port 8000 inside the container.