Introduction to MT5 Docker
Relevant source files
The following files were used as context for generating this wiki page:
MT5 Docker is a specialized containerization solution designed to run the MetaTrader 5 (MT5) terminal in an isolated Linux environment using Wine. Its primary purpose is to provide a production-ready, automated infrastructure for algorithmic trading, offering remote access via a web-based VNC interface and a robust gRPC bridge for Python-driven control through the mt5linux library.
The project features a dual-Python architecture to ensure compatibility between modern Linux tooling and MT5's specific requirements. It includes automated account provisioning, health monitoring with auto-recovery, and support for .NET-based Expert Advisors (EAs). By encapsulating the complex Wine and MT5 dependency chain, it allows developers to deploy trading bots consistently across different host environments.
Sources: README.md:1-25, docker/compose.yaml:49-65
System Architecture
The MT5 Docker environment is built on a Debian-based image that orchestrates several layers of software to bridge the gap between Windows-native trading software and Linux-based automation.
Dual Python Architecture
The system utilizes two distinct Python environments to maintain optimal compatibility:
- System Python (Linux): Typically version 3.13, used for modern management tools, CI/CD, and
mt5linuxcompatibility. - Wine Python (Windows): Version 3.12, specifically required for compatibility with
numpy 1.26.4and the MetaTrader 5 Python package.
Sources: README.md:86-95, tests/test_static.py:101-115
Core Components
The following diagram illustrates the high-level architecture and data flow between the internal container services and external interfaces:
The diagram shows how KasmVNC provides a web interface to the virtual display, while the gRPC bridge facilitates communication between external Python clients and the MT5 terminal running under Wine.
Sources: README.md:31-50, docker/compose.yaml:26-30
Service Orchestration and Startup
Container lifecycle is managed through a sequence of consolidated shell scripts and the s6-overlay process supervisor.
Startup Sequence
The startup process follows a strict "Fail-Fast" design to ensure the environment is correctly initialized before trading operations begin.
- Entrypoint (
start.sh): Sets environment variables, checks basic dependencies likecurlandwine, and invokes the setup script. - Setup (
setup.sh): Initializes the Wine prefix (installing Mono, Gecko, and Python), installs the MT5 terminal viamt5setup.exe, and copies the gRPC bridge files. - Service Supervisor (
s6-overlay): Manages the persistent execution of the MT5 terminal and the gRPC bridge, monitoring them for failures.
Sources: docker/container/metatrader/start.sh:15-85, docker/container/metatrader/setup.sh:220-250, tests/test_static.py:440-470
Account Provisioning (Zero-Touch)
When MT5_AUTO_CREATE_DEMO is enabled, the system uses xdotool to automate the GUI-based "Open an Account" wizard.
This flow demonstrates the "zero-touch" provisioning path where the system automatically handles GUI interactions to secure a demo account.
Sources: docker/container/metatrader/open_demo_account.py:15-50, README.md:144-165
Communication Protocol (gRPC Bridge)
The project replaces legacy RPyC communication with a high-performance gRPC bridge defined in mt5.proto. This service runs inside the Wine environment and translates gRPC calls from the Linux host or remote clients into MT5 API commands.
Key Service Methods
| Category | Method | Description |
|---|---|---|
| Terminal | HealthCheck | Returns status of terminal and broker connection. |
| Account | AccountInfo | Returns account details as JSON-serialized data. |
| Market | CopyRatesFrom | Returns historical price data as a NumpyArray. |
| Trading | OrderSend | Sends a trade request to the broker. |
| Provisioning | CreateDemoAccount | Triggers the automated demo account wizard. |
Sources: docker/container/metatrader/mt5.proto:170-220
Data Serialization
Because the bridge must cross between different Python versions and environments, it uses DictData (JSON-serialized dictionaries) and NumpyArray (bytes with dtype/shape metadata) for complex structures.
Sources: docker/container/metatrader/mt5.proto:95-115
Configuration and Environment
System behavior is controlled through environment variables typically defined in a .env file or the compose.yaml.
Critical Configuration Options
| Variable | Default | Description |
|---|---|---|
MT5_LOGIN | - | Account number (triggers manual/auto login). |
MT5_AUTO_CREATE_DEMO | 0 | If 1, creates a demo account if no login is provided. |
ENABLE_WIN_DOTNET | 1 | Installs .NET Framework 4.8 via winetricks for EAs. |
AUTO_RECOVERY_ENABLED | 1 | Restarts MT5/Bridge on health check failure. |
WINEPREFIX | /config/.wine | Directory for the persistent Wine environment. |
Sources: README.md:213-240, docker/compose.yaml:50-65
Health Monitoring and Recovery
The health_monitor.sh script runs as a background daemon, periodically verifying the status of the terminal and the gRPC bridge. If failures exceed a defined threshold, it uses a RESTART_TOKEN to signal the s6-overlay supervisor to perform a full restart of the trading services.
Sources: tests/test_static.py:465-480, docker/container/metatrader/start.sh:105-110
Conclusion
MT5 Docker provides a comprehensive, automated environment for MetaTrader 5 deployment on Linux. By integrating GUI automation for account provisioning, a standardized gRPC bridge for remote control, and robust health monitoring, it simplifies the operational complexity of running Windows-based trading software in a cloud-native or containerized fashion.
Sources: README.md:1-25, docker/container/metatrader/setup.sh:240-255