Advanced Docker Compose Usage
Relevant source files
The following files were used as context for generating this wiki page:
The mt5linux project utilizes a highly parametrized Docker Compose architecture to facilitate isolated MetaTrader 5 (MT5) instances. This system is designed to provide a "single source of truth" for container configurations, allowing for flexible transitions between development, testing, and production environments through environment variable overrides.
The core of this architecture is the docker-compose.yaml file, which manages gRPC server access, VNC GUI ports, and health check endpoints. By leveraging isolated volumes and per-instance networks, the system ensures that multiple containers can run in parallel without resource collision or cross-talk.
Sources: DOCKER_COMPOSE_USAGE.md:3-8, docker-compose.yaml:3-10, docker-compose.yaml:70-75
Parametrization and Configuration
The Docker Compose setup is driven by environment variables that define container naming, network identity, and port mapping. This allows developers to spin up specific environments—such as isolated test runners or persistent production bridges—by simply modifying shell variables or .env files.
Core Environment Variables
The following variables are used to customize the deployment:
| Variable | Default Value | Description |
|---|---|---|
MT5_CONTAINER_NAME | mt5linux-test | Defines the container name and the prefix for associated volumes. |
MT5_GRPC_PORT | 28812 | The host port mapped to the internal gRPC server (port 8001). |
MT5_VNC_PORT | 23000 | The host port mapped to the internal VNC GUI (port 3000). |
MT5_HEALTH_PORT | 28002 | The host port mapped to the internal health check (port 8002). |
MT5_NETWORK_NAME | ${MT5_CONTAINER_NAME}-network | The name of the isolated bridge network for the instance. |
Sources: DOCKER_COMPOSE_USAGE.md:14-25, docker-compose.yaml:45-55, docker-compose.yaml:76-78
Configuration Precedence
The system resolves configuration using a specific priority:
- Explicit Shell Variables: Variables set directly in the command line (e.g.,
MT5_GRPC_PORT=38812 docker compose up). - Environment Files: The system defaults to
.env, but can be pointed to files like.env.testfor isolated defaults via theENV_FILEvariable. - Default Values: Hardcoded fallbacks within the
docker-compose.yamlfile.
Sources: DOCKER_COMPOSE_USAGE.md:10-12, docker-compose.yaml:57-58
System Architecture and Isolation
The architecture emphasizes strict isolation between instances. Every container instance receives its own set of dedicated resources to prevent interference during parallel execution.
Multi-Container Resource Mapping
The following diagram illustrates how environment variables are used to derive isolated host resources:
The diagram shows the relationship between input environment variables and the resulting isolated Docker resources.
Sources: docker-compose.yaml:47-55, docker-compose.yaml:70-78, tests/integration/test_multi_container_isolation.py:16-20
Resource Isolation Strategy
- Volumes: Volumes are named based on the container name (e.g.,
mt5linux-test_settings). This ensures that production data is never overwritten by test runs. - Networks: Each instance creates a dedicated bridge network. This prevents "cross-talk" and IP collisions when running multiple MT5 instances on the same host.
- Ports: The system utilizes different port ranges for test (28xxx) and production (38xxx) to allow simultaneous operation.
Sources: docker-compose.yaml:3-10, docker-compose.yaml:70-78, DOCKER_COMPOSE_USAGE.md:82-88
Integration with Testing Frameworks
The pytest suite heavily relies on these advanced compose features to perform integration testing without affecting local MT5 installations.
Automated Test Lifecycle
When running tests, the conftest.py fixture manages the container lifecycle. It typically:
- Loads
.env.testfor isolated defaults. - Removes any stale volumes from previous runs to ensure a clean state.
- Starts the container using the defined
MT5_GRPC_PORT. - Tears down the resources after completion.
Sources: DOCKER_COMPOSE_USAGE.md:30-36, DOCKER_COMPOSE_USAGE.md:82-88
Parallel Instance Validation
The project includes specific tests to ensure that the parametrization logic prevents collisions. The test_multi_container_isolation.py script validates that multiple sets of parameters result in pairwise-distinct resource names.
# Example of distinct instances used in isolation tests
INSTANCES: tuple[dict[str, str], ...] = (
{
"MT5_CONTAINER_NAME": "mt5-iso-a",
"MT5_GRPC_PORT": "18001",
"MT5_NETWORK_NAME": "mt5-iso-a-net",
},
{
"MT5_CONTAINER_NAME": "mt5-iso-b",
"MT5_GRPC_PORT": "18002",
"MT5_NETWORK_NAME": "mt5-iso-b-net",
},
)
Sources: tests/integration/test_multi_container_isolation.py:23-36
Health Monitoring and Security
The Docker Compose configuration includes internal health checks to ensure the gRPC bridge is responsive before client applications attempt to connect.
Health Check Mechanism
The container performs a TCP check on its internal gRPC port to verify service availability:
- Internal Port: 8001
- Interval: 30 seconds
- Start Period: 120 seconds (to allow for Wine and MT5 initialization)
Sources: docker-compose.yaml:61-68, mt5linux/constants.py:32-35
Security and Privileges
To allow MetaTrader 5 to run correctly under Wine within a container, specific security capabilities are required:
- CAP_ADD:
SYS_PTRACEis enabled to allow process debugging/instrumentation. - Security Opt:
seccomp:unconfinedis used to prevent the container from blocking specific system calls required by the MT5 runtime.
Sources: docker-compose.yaml:59-60, AGENTS.md:16
Advanced Usage Examples
Running Parallel Production and Test Instances
You can run a production bridge and a test environment simultaneously by varying the ports and names:
# Terminal 1: Production Bridge
MT5_CONTAINER_NAME=mt5-prod \
MT5_GRPC_PORT=38812 \
docker compose up -d
# Terminal 2: Test Runner
MT5_CONTAINER_NAME=mt5-test-unit \
MT5_GRPC_PORT=28812 \
pytest tests/
Sources: DOCKER_COMPOSE_USAGE.md:90-104, docker-compose.yaml:26-31
Cleaning Up Isolated Resources
Because volumes are named dynamically, a standard docker compose down may leave orphaned volumes. To fully purge an environment:
MT5_CONTAINER_NAME=mt5-custom docker compose down -v
Sources: DOCKER_COMPOSE_USAGE.md:73-80, DOCKER_COMPOSE_USAGE.md:130-140
Conclusion
The advanced Docker Compose configuration in mt5linux provides a robust, scalable environment for MetaTrader 5 automation. By treating the compose file as a parametrized template, the project achieves high levels of isolation and flexibility, making it suitable for everything from local unit testing to multi-account production deployments.