Docker Infrastructure & Containerization
Relevant source files
The following files were used as context for generating this wiki page:
The Docker infrastructure in this project provides a unified runtime environment for the various microservices that compose the Instagram automation bot. It facilitates the orchestration of the React-based frontend, the Express API server, the Python automation runners, and the Convex backend integration.
The containerization strategy ensures consistent development and production environments, managing service dependencies, environment variables, and inter-service communication via a centralized configuration.
Sources: AGENTS.md:46, AGENTS.md:65
Service Architecture
The system is organized into several distinct services that interact to perform automated tasks. These services are defined and managed through Docker orchestration.
Core Services
| Service | Description | Technology Stack |
|---|---|---|
| Frontend | React Router application providing the user interface for monitoring and management. | React, Vite |
| Server | Express API and WebSocket server acting as a bridge between the UI and automation. | Node.js, Express |
| Python Runner | Runtime environment for executing Instagram domain actions and browser automation. | Python, Playwright/Selenium |
| Convex Backend | Cloud-synced database and serverless function layer for persistent state. | Convex |
| Data Uploader | Ingest service for CSV and workflow artifacts. | Node.js |
The following diagram illustrates the high-level interaction between the containerized components:
The diagram shows how local containers communicate via a Docker network while persisting state to the external Convex cloud.
Sources: AGENTS.md:46-55, server/shared/convexClient.ts:16-25
Environment Configuration
Container behavior and service connectivity are governed by environment variables managed within the Docker infrastructure.
Critical Environment Variables
- CONVEX_URL: The target cloud URL for the Convex backend. The system automatically converts
.convex.cloudto.convex.sitefor HTTP action endpoints. - INTERNAL_API_KEY: A secret token used for secure communication between the Express server/Python runners and the Convex HTTP surface.
- SERVER_URL: Used to point automation runners to the local Express API.
- WORKFLOW_MAX_CONCURRENCY: Defines the maximum number of simultaneous workflows the infrastructure can support (defaulting to 3).
Sources: server/shared/convexClient.ts:16-30, server/workflows/routes.ts:153-158, tests/convex/http.test.ts:152-155
Network & Security
The infrastructure utilizes an internal HTTP surface to allow services to communicate securely without exposing every component to the public internet.
Internal API Authentication
Access to internal routes (such as /api/profiles, /api/workflows, and /api/keywords) is restricted via a Bearer token mechanism using the INTERNAL_API_KEY. Requests without a valid key are rejected with a 401 Unauthorized or 500 configuration error.
This sequence shows the authentication flow for internal service-to-service communication.
Sources: server/shared/convexClient.ts:162-170, tests/convex/http.test.ts:18-35, tests/convex/http.test.ts:241-245
Deployment & Development Lifecycle
The project utilizes standardized commands to build and run the containerized stack, ensuring that all dependencies (Frontend, Server, and Python) are correctly initialized.
Deployment Commands
docker compose up --build: Rebuilds all service images and starts the container cluster.npm run dev: Executes development modes across the root, frontend, and server directories.
Sources: AGENTS.md:58-65
Conclusion
The Docker infrastructure provides the necessary isolation and orchestration to manage the complex interactions between the project's multi-language components. By centralizing configuration through environment variables and securing inter-service traffic with internal API keys, the system maintains a robust and scalable environment for Instagram automation workflows.