Docker Container Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The MetaTrader5 Docker Image provides a containerized environment for running the MetaTrader 5 (MT5) terminal on Linux. It leverages Wine to execute the Windows-based MT5 terminal and exposes its functionality via a gRPC bridge and a KasmVNC web interface. This architecture allows for headless operation, automated trading through Python, and remote GUI access.
The system is built upon a Debian base image and features a dual Python architecture (System Python 3.13 and Wine-based Python 3.12) to ensure compatibility between modern Linux tooling and the specific requirements of the MetaTrader5 Python library and NumPy.
Sources: README.md:1-25, README.md:104-110
Core Architectural Components
The architecture consists of several layered components working together to bridge the gap between the Linux container environment and the Windows-based MT5 terminal.
Layered Services Diagram
The following diagram illustrates the relationship between the host, the container layers, and the exposed services.
Multi-Python Environment
The container utilizes two distinct Python environments to handle different responsibilities:
- System Python (3.13): Used for modern tooling, container management scripts, and compatibility with the
mt5linuxlibrary. - Wine Python (3.12): Installed within the Wine prefix to interact directly with the MetaTrader5 terminal via the official
MetaTrader5package, specifically pinned to version 3.12 for NumPy 1.26.4 compatibility.
Sources: README.md:104-110, docker/container/metatrader/setup.sh:135-145
Provisioning and Lifecycle Management
Container lifecycle is managed through a combination of startup scripts and the s6-overlay process supervisor.
Startup Sequence
The startup process is split between start.sh (orchestration) and setup.sh (installation and configuration).
| Script | Responsibility | Key Actions |
|---|---|---|
start.sh | Orchestration | Exports environment variables, sets startup markers, executes setup.sh, and launches background monitors. |
setup.sh | Provisioning | Initializes Wine prefix, installs Wine Mono/Gecko, installs MT5 terminal, and configures the gRPC bridge. |
health_monitor.sh | Supervision | Periodically checks terminal and bridge health; requests restarts via RESTART_TOKEN upon failure. |
Sources: docker/container/metatrader/start.sh:10-50, docker/container/metatrader/setup.sh:10-15, tests/test_static.py:615-630
Initialization Flow
The initialization flow ensures that the Wine environment is idempotent and resilient to partial failures.
Remote Communication Architecture
The container facilitates interaction through two primary interfaces: a GUI for manual control and a gRPC API for programmatic access.
gRPC Bridge System
The bridge acts as a translator between Linux gRPC calls and the Windows MT5 Python API. It uses a standalone protobuf definition (mt5.proto) to implement the MT5Service.
- Service Definition: Defined in
docker/container/metatrader/mt5.proto. - Implementation:
bridge.py(copied to Wine'ssite-packages/mt5linuxat runtime). - Data Serialization: Uses JSON-serialized strings for complex objects and raw bytes for NumPy arrays to maintain high performance.
Sources: docker/container/metatrader/mt5.proto:240-275, docker/container/metatrader/setup.sh:310-330
Interface Mapping
| Component | Protocol | Default Port | Description |
|---|---|---|---|
| KasmVNC | HTTP/HTTPS | 3000 | Provides the web-based GUI for the MT5 terminal. |
| gRPC Bridge | TCP (gRPC) | 8001 | Programmatic API for mt5linux client library. |
| Health Check | TCP | 8002 | Port used for container health status monitoring. |
Sources: docker/compose.yaml:33-36, README.md:213-220
Security and Resource Constraints
The container requires specific security privileges and resource allocations to run the MT5 terminal under Wine effectively.
- Capabilities: Requires
SYS_PTRACEfor certain Expert Advisor (EA) protections and MetaQuotes software behavior. - Security Options: Operates with
seccomp:unconfinedto allow the Wine server to manage Windows processes. - Resource Limits: Typically deployed with a 4G memory limit and 2.0 CPU limit.
- Ulimits: Sets
nofilelimits to65536to handle the large number of file descriptors required by Wine and multiple MT5 connections.
Sources: docker/compose.yaml:69-75, docker/compose.yaml:85-95
Conclusion
The architecture of mt5-docker is designed around the robust isolation of the Windows MT5 environment within a Linux container. By employing a dual-Python approach and a process-managed gRPC bridge, the system provides a production-ready platform for automated trading that remains accessible via standard web technologies. The use of s6-overlay and specialized health monitors ensures high availability, making it suitable for 24/7 trading operations.