Docker Deployment Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Docker deployment setup for mt5linux provides a containerized environment to run MetaTrader 5 (MT5) on Linux systems. It utilizes a gRPC bridge to facilitate communication between Linux-based Python clients (both synchronous and asynchronous) and the MT5 terminal running under Wine within a Debian-based Docker image.
The primary purpose of this setup is to ensure a consistent, isolated, and scalable environment for algorithmic trading and automated testing. The configuration is centralized through a parametrized docker-compose.yaml file, which serves as the single source of truth for container orchestration, networking, and volume management.
Sources: README.md:1-10, docker-compose.yaml:1-10, DOCKER_COMPOSE_USAGE.md:3-8
Container Architecture
The deployment architecture consists of a Debian-based container running the marlonsc/mt5-docker image. This image encapsulates the MT5 terminal and a gRPC server bridge. The container exposes multiple ports for different services, including gRPC for API calls, VNC for GUI access, and a dedicated health check port.
Component Diagram
The following diagram illustrates the relationship between the host system, the Docker container, and the internal services.
The diagram shows how the external client interacts with internal container services via port mapping.
Sources: docker-compose.yaml:38-50, DOCKER_COMPOSE_USAGE.md:12-25, mt5linux/settings.py:45-60
Parametrized Configuration
The deployment supports extensive parametrization via environment variables, allowing for parallel execution of multiple isolated instances. Configuration defaults are managed by MT5Settings and can be overridden using .env or .env.test files.
Port Mapping Strategies
The system uses three distinct port ranges to avoid collisions between production and testing environments:
| Service | Internal Port | Test Default (Host) | Production Default (Host) |
|---|---|---|---|
| gRPC Server | 8001 | 28812 | 38812 |
| VNC GUI | 3000 | 23000 | 33000 |
| Health Check | 8002 | 28002 | 38002 |
Sources: docker-compose.yaml:12-25, mt5linux/settings.py:45-65, README.md:175-185
Environment Variables
Key variables used to customize the deployment include:
- MT5_CONTAINER_NAME: Defines the container name and acts as a prefix for volumes (Default:
mt5linux-test). - MT5_LOGIN / MT5_PASSWORD / MT5_SERVER: Credentials for the MetaTrader 5 account.
- ENV_FILE: Path to the environment file containing credentials (Default:
.env).
Sources: DOCKER_COMPOSE_USAGE.md:18-35, docker-compose.yaml:26-36, tests/conftest.py:50-65
Isolation and Resource Management
Isolation is achieved by ensuring that every instance of a container has unique resource names. This allows multiple MT5 instances to run in parallel without cross-talk or port collisions.
The sequence shows the automated setup of an isolated environment during testing.
Sources: tests/integration/test_multi_container_isolation.py:15-30, docker-compose.yaml:68-80, tests/conftest.py:230-260
Volume Persistence
Volumes are automatically named based on the MT5_CONTAINER_NAME variable. This ensures that configuration data is persisted separately for each instance.
- Volume Name Pattern:
${MT5_CONTAINER_NAME}_settings - Internal Mount Point:
/config(UID/GID 911)
Sources: docker-compose.yaml:68-75, DOCKER_COMPOSE_USAGE.md:85-100
Health and Lifecycle Management
The Docker setup includes automated health checks and lifecycle controls to ensure service reliability.
Health Check Logic
The container uses a custom health check that verifies if the gRPC server is listening on its internal port. In the test environment, conftest.py implements a more rigorous check by calling GetConstants through the gRPC interface to confirm the MT5 terminal is fully initialized and responsive.
healthcheck:
test: ["CMD", "bash", "-c", "echo >/dev/tcp/localhost/8001"]
interval: 30s
timeout: 10s
retries: 3
start_period: 120s
Sources: docker-compose.yaml:58-65, tests/conftest.py:175-195
Service Startup Flow
- Environment Loading:
conftest.pyloads.env.testand.envfiles. - Container Validation: System checks if a container with
MT5_CONTAINER_NAMEis already running. - gRPC Readiness: System waits for the gRPC service with progressive backoff (up to 7 minutes).
- Codegen: Optionally runs
codegen_enums.pyto ensure local protocol buffers are up to date.
Sources: tests/conftest.py:270-320, mt5linux/settings.py:75-80
Deployment Commands
Basic management of the Docker environment is performed through standard Docker Compose commands, enhanced by environment variable overrides.
# Start with default test settings
docker compose up -d
# Start production-like instance
MT5_CONTAINER_NAME=mt5-prod \
MT5_GRPC_PORT=38812 \
MT5_VNC_PORT=33000 \
docker compose up -d
# Cleanup including volumes
docker compose down -v
Sources: DOCKER_COMPOSE_USAGE.md:65-80, README.md:140-148
Conclusion
The mt5linux Docker deployment setup provides a robust, isolated infrastructure for running MetaTrader 5 on Linux. By leveraging gRPC and Docker Compose parametrization, the project enables seamless transitions between development, testing, and production environments while maintaining strict resource isolation.