Docker Services¶

Carbon Connect uses Docker Compose to run its three core infrastructure services locally: PostgreSQL (with pgvector), Valkey (Redis-compatible cache), and Meilisearch (full-text search). An optional dev profile adds database and cache management UIs.

Architecture Overview¶

graph LR
    subgraph Docker Compose
        PG["PostgreSQL 16<br/>+ pgvector<br/>:5433"]
        VK["Valkey 8<br/>(Redis-compatible)<br/>:6379"]
        MS["Meilisearch 1.6<br/>:7700"]
    end

    subgraph Dev Profile
        AD["Adminer<br/>(DB UI)<br/>:8080"]
        VC["Valkey Commander<br/>(Cache UI)<br/>:8081"]
    end

    API["FastAPI<br/>:8000"] --> PG
    API --> VK
    API --> MS
    AD --> PG
    VC --> VK

Services¶

PostgreSQL 16 with pgvector¶

The primary relational database extended with pgvector for 768-dimensional vector similarity search.

Health Check: Runs pg_isready every 10 seconds with 5 retries.

Init Script: The file scripts/init-extensions.sql is mounted to /docker-entrypoint-initdb.d/ and runs on first container creation. It creates the pgvector extension required for embedding storage and similarity search.

Connection Strings:

postgresql://grant_user:grant_password_dev@localhost:5433/grant_engine

postgresql+asyncpg://grant_user:grant_password_dev@localhost:5433/grant_engine

Valkey 8¶

Redis-compatible in-memory data store used for caching, session storage, and as the Celery message broker and result backend. Valkey is 100% compatible with Redis clients and is approximately 20% cheaper on AWS (ElastiCache).

Health Check: Runs valkey-cli ping every 10 seconds with 5 retries.

Connection URL: redis://localhost:6379/0

Meilisearch 1.6¶

High-performance full-text search engine providing sub-100ms search latency across 100k+ grant documents.

Health Check: Runs curl -f http://localhost:7700/health every 10 seconds with 5 retries.

Environment Variables (container-level):

Dev Profile Services¶

These services are only started when using the dev profile. They provide web-based management interfaces for development convenience.

Adminer (Database UI)¶

Access at http://localhost:8080 and connect with:

• System: PostgreSQL
• Server: postgres (Docker service name)
• Username: grant_user
• Password: grant_password_dev
• Database: grant_engine

Valkey Commander (Cache UI)¶

Access at http://localhost:8081 to browse keys, monitor connections, and inspect Celery queues.

Commands¶

Starting Services¶

# Start core services (PostgreSQL, Valkey, Meilisearch)
docker compose up -d

# Start with dev tools (adds Adminer and Valkey Commander)
docker compose --profile dev up -d

# Start a specific service
docker compose up -d postgres

Stopping Services¶

# Stop all running containers (preserves data)
docker compose down

# Stop and remove all volumes (fresh start, destroys data)
docker compose down -v

# Stop only dev profile services
docker compose --profile dev down

Monitoring¶

# View running containers and their health status
docker compose ps

# Follow logs for all services
docker compose logs -f

# Follow logs for a specific service
docker compose logs -f postgres
docker compose logs -f valkey
docker compose logs -f meilisearch

Direct Container Access¶

# Open PostgreSQL interactive shell
docker exec -it granted_carbon_postgres psql -U grant_user -d grant_engine

# List database tables
docker exec granted_carbon_postgres psql -U grant_user -d grant_engine -c "\dt"

# Check pgvector extension
docker exec granted_carbon_postgres psql -U grant_user -d grant_engine -c "SELECT * FROM pg_extension WHERE extname = 'vector';"

# Ping Valkey
docker exec granted_carbon_valkey valkey-cli ping

# List Valkey keys
docker exec granted_carbon_valkey valkey-cli keys "*"

# Check Meilisearch health
curl http://localhost:7700/health

# List Meilisearch indexes
curl http://localhost:7700/indexes -H "Authorization: Bearer meilisearch_dev_master_key_change_in_prod"

Volumes¶

Docker Compose defines three named volumes for data persistence across container restarts:

Network¶

All services share a single Docker network:

Services can reference each other by their Docker Compose service names (postgres, valkey, meilisearch) within the network. External access from the host uses localhost with the mapped ports.

Troubleshooting¶

docker compose logs -f postgres

curl http://localhost:7700/indexes \
  -H "Authorization: Bearer meilisearch_dev_master_key_change_in_prod"

docker compose down meilisearch
docker compose up -d meilisearch

docker compose ps valkey
docker exec granted_carbon_valkey valkey-cli ping

# Remove unused Docker resources
docker system prune

# Remove specific project volumes (destroys data)
docker compose down -v

Docker Compose File Reference¶

The full docker-compose.yml is located at the project root. Key structural notes:

• Compose version: 3.9
• Restart policy: All services use unless-stopped
• Health checks: All three core services define health checks with 10-second intervals and 5 retries
• Init script: PostgreSQL mounts scripts/init-extensions.sql as a read-only init script
• Dev profile: Adminer and Valkey Commander are gated behind the dev profile to keep the default startup lightweight