Docker Services & Orchestration
Relevant source files
The following files were used as context for generating this wiki page:
The Docker Services and Orchestration layer in CodeBot provides a containerized environment designed for consistent development, testing, and production deployment. By leveraging Docker Compose, the project orchestrates multiple microservices, including the core Python bot, a web application, and various infrastructure components such as databases, caches, and monitoring tools.
This architecture ensures that all dependencies, such as MongoDB and Redis, are isolated and easily configurable through environment variables. The orchestration setup supports different profiles, allowing developers to switch between a lightweight development environment with hot-reloading and a full-scale production stack integrated with observability tools like Prometheus and Grafana.
Sources: docker-compose.yml:1-12, CLOUD.md:1-10, docker-compose.dev.yml:1-10
Service Architecture Overview
The system is composed of several specialized containers that communicate over a dedicated bridge network. The primary application logic resides in the code-keeper-bot service, which depends on data storage and caching services to function correctly.
Core Infrastructure Services
The infrastructure layer consists of persistence and caching layers that the application services rely upon for state management and performance optimization.
- MongoDB: The primary database used for storing snippets, user metadata, and repository information. It is configured with health checks to ensure availability before dependent services start.
- Redis: An optional caching layer used for session management, rate limiting, and performance optimization.
- Mongo Express: A web-based administrative interface for MongoDB, typically used during development or monitoring.
Sources: docker-compose.yml:15-62, docker-compose.dev.yml:15-53
Application Logic Services
The application layer contains the bot and the webapp. These services are built from the same Dockerfile but targeted at different stages (e.g., production vs development).
- Code Keeper Bot: The main service responsible for Telegram bot interactions and background tasks like backups.
- Code Keeper Bot Dev: A specialized development version that mounts the local source code into the container to enable hot-reloading via
watchdogor similar tools.
Sources: docker-compose.yml:64-188, docker-compose.dev.yml:55-108
System Interaction Diagram
The following diagram illustrates how the Docker containers are orchestrated and how they communicate within the internal network.
This diagram shows the relationship between the main bot service, its storage dependencies, and the entry points for external users.
Sources: docker-compose.yml:15-188, GUIDES/ARCHITECTURE.md:20-50
Monitoring & Observability Stack
CodeBot includes an extensive observability stack, defined through Docker Compose profiles. This allows the stack to be optionally deployed to monitor system health, latency, and error rates.
- Prometheus: Scrapes metrics from the application and other services. It is configured to retain data for 200 hours.
- Grafana: Provides dashboards for visualizing the metrics collected by Prometheus. It includes pre-provisioned dashboards.
- Jaeger: A tracing backend used for distributed tracing via OpenTelemetry (OTLP), allowing developers to inspect request flows and latency across service boundaries.
- Alertmanager: Handles alerts sent by Prometheus, routing notifications based on severity.
Sources: docker-compose.yml:218-306, webapp/templates/settings.html:565-650
Observability Data Flow
The flow of metrics and traces from the application to the monitoring tools is depicted below.
This sequence illustrates the push-pull dynamics of the monitoring stack. Traces are pushed via OTLP while metrics are scraped by Prometheus.
Sources: docker-compose.yml:106-115, docker-compose.yml:256-306, GUIDES/ARCHITECTURE.md:52-80
Configuration and Environment Variables
The Docker services are highly configurable via environment variables, typically managed in a .env file. These variables control everything from database credentials to feature flags and alert thresholds.
Key Configuration Categories
| Category | Key Variables | Description |
|---|---|---|
| Database | MONGODB_URL, DATABASE_NAME | Connection strings and DB target. |
| Bot Settings | BOT_TOKEN, ADMIN_USER_IDS | Essential Telegram authentication and permissions. |
| Monitoring | ENABLE_METRICS, SENTRY_DSN | Toggles for observability features. |
| Alerting | ALERT_ERRORS_PER_MINUTE, ALERT_COOLDOWN_SEC | Thresholds for anomaly detection and alert noise reduction. |
| External | GITHUB_TOKEN, PASTEBIN_API_KEY | Integrations for external code hosting/sharing. |
Sources: docker-compose.yml:74-138, CLOUD.md:66-73
Service Dependencies and Health Checks
Docker Compose uses depends_on with service_healthy conditions to ensure that the infrastructure is ready before the application starts.
depends_on:
mongodb:
condition: service_healthy
redis:
condition: service_healthy
Sources: docker-compose.yml:158-163, docker-compose.dev.yml:95-98
Development vs Production Profiles
The project utilizes Docker Compose profiles to manage the environment complexity.
- Production: Run with
docker-compose --profile production up. Includes Nginx as a reverse proxy and hardened security settings. - Development: Run with
docker-compose --profile development up. Maps the current directory to/appfor live code changes and setsDEBUG: true. - Monitoring: Run with
docker-compose --profile monitoring up. Spins up the Prometheus, Grafana, and Jaeger instances.
Sources: docker-compose.yml:180-335, docker-compose.dev.yml:110-150
Conclusion
The Docker services and orchestration setup for CodeBot provides a robust and flexible foundation for managing the bot's lifecycle. By partitioning the system into distinct services for storage, logic, and monitoring, the project achieves high maintainability and ease of deployment. The use of profiles allows developers to tailor the environment to their specific needs, whether they are performing local hot-reloaded development or scaling a production instance with full observability.
Sources: docker-compose.yml:320-350, CLOUD.md:12-25