Docker Environment
Relevant source files
The following files were used as context for generating this wiki page:
ClassMate utilizes a containerized architecture to manage its diverse ecosystem of AI services, databases, and monitoring tools. The Docker environment is designed to support the entire lifecycle of the application, from local development to high-scale production deployments. It provides a consistent runtime environment across different stages, ensuring that dependencies such as FastAPI, PostgreSQL, Redis, and various AI workers are isolated and easily Orchestrated.
The environment is structured into multiple configurations depending on the target use case: a core stack for local development, an extended stack including monitoring for observability, and a production-grade configuration optimized for resource limits and security. These configurations are managed primarily through Docker Compose, allowing developers to spin up the entire backend with a single command.
Sources: infra/README.md:14-25, README.md:12-32, PROJECT_STRUCTURE.md:104-108
Core Service Architecture
The core Docker environment consists of several interconnected services that handle API requests, background task processing, and persistent storage. All services communicate over a dedicated bridge network.
Service Breakdown
| Service | Image/Build | Port(s) | Role |
|---|---|---|---|
| API | ai_backend/Dockerfile | 8000 | FastAPI backend handling REST and WebSocket requests |
| Worker | ai_workers/Dockerfile | N/A | Celery worker for asynchronous AI tasks (transcription, notes) |
| Beat | ai_workers/Dockerfile | N/A | Celery beat scheduler for periodic tasks |
| Postgres | postgres:15 | 5432 | Primary relational database with vector support |
| Redis | redis:7-alpine | 6379 | Message broker for Celery and caching layer |
| MinIO | minio/minio:latest | 9000/9001 | S3-compatible object storage for audio files |
| Nginx | nginx:alpine | 80/443 | Reverse proxy for SSL termination and request routing |
Sources: infra/docker/docker-compose.yml:5-103, docker-compose.prod.yml:10-141, infra/README.md:21-27
System Data Flow
The following diagram illustrates how requests and data flow between the containerized services:
The data flow ensures that heavy AI processing is decoupled from the user-facing API through Redis and Celery workers.
Sources: README.md:16-32, PROJECT_STRUCTURE.md:144-154
Environment Configurations
The project provides three primary Docker Compose entry points to cater to different operational needs.
Local Development
Located in infra/docker/docker-compose.yml, this configuration focuses on simplicity and ease of access. It exposes database and storage ports directly to the host for easier debugging.
Sources: infra/README.md:16-19, infra/docker/docker-compose.yml:1-110
Monitoring and Observability
The monitoring stack adds a layer of observability to the core services. It is defined in infra/docker/docker-compose-monitoring.yml and includes tools for logging, tracing, and metrics.
- Loki: Centralized log aggregation.
- Grafana: Visualization of metrics and logs.
- Jaeger: Distributed tracing for identifying bottlenecks.
- PgBouncer: Connection pooling for PostgreSQL to handle high concurrency.
Sources: infra/docker/docker-compose-monitoring.yml:105-164, README.md:27-32
Production Environment
The docker-compose.prod.yml file introduces resource constraints and enhanced security configurations.
- Resource Limits: API and Workers are constrained (e.g., Worker limited to 2G RAM and 2 CPUs).
- Logging: Implements
json-filelogging with rotation (max-size 10m). - Healthchecks: Core services like Postgres and Redis include healthcheck commands to ensure service availability before the API starts.
- OpenTelemetry: The API service is configured to export traces to a Tempo service via OTLP.
Sources: docker-compose.prod.yml:4-9, docker-compose.prod.yml:92-115, docker-compose.prod.yml:181-220
Configuration and Management
Environment Variables
Services are configured via environment variables, typically stored in a .env file. Key variables include:
DATABASE_URL: Connection string for Postgres.REDIS_URL: Connection string for the message broker.MINIO_ENDPOINT: Address for object storage.JWT_SECRET_KEY: Key used for authentication tokens.
Sources: infra/README.md:29-36, docker-compose.prod.yml:71-82
Management Scripts
A utility script scripts/launch.sh provides a menu-driven interface to manage the Docker environment.
# Options provided by launch.sh:
# 1. Start Core Backend (DB + Redis + API)
# 2. Start Full Stack (Core + Monitoring)
# 5. Stop All Servers
# 7. Run Health Check
Sources: scripts/launch.sh:10-21
Deployment Verification
The scripts/verify_deployment.sh script automates the health check of the Docker environment by:
- Checking if containers are in the "Up" state.
- Querying the
/api/v1/public/healthendpoint. - Verifying accessibility of the Traefik/Nginx gateway.
Sources: scripts/verify_deployment.sh:5-30
Conclusion
The Docker environment for ClassMate provides a robust, scalable foundation for the application's AI-heavy workloads. By utilizing specialized configurations for development, monitoring, and production, the system ensures that developers have the tools needed for local work while maintaining the performance and security standards required for high-traffic environments. The use of Celery and Redis within Docker allows for horizontal scaling of AI workers to meet user demand.
Sources: README.md:12-14, infra/README.md:121-125