Custom Container Builds
Relevant source files
The following files were used as context for generating this wiki page:
The mt5-docker project utilizes a sophisticated multi-stage build and runtime initialization process to create a specialized environment for running MetaTrader 5 (MT5) within a Docker container. The primary purpose is to provide a stable, reproducible Linux-based environment (Debian) that uses Wine to execute the Windows-native MT5 terminal and a dual-Python bridge for remote control via gRPC or RPyC.
Custom builds are managed through a combination of BuildKit-enabled Dockerfiles, Docker Compose configurations for environment pinning, and shell scripts that handle the complex orchestration of Wine prefixes and dependency injection. This architecture ensures that MT5 can be run headlessly while maintaining compatibility with modern Python tooling like Poetry and gRPC.
Sources: README.md:1-40, docker/compose.yaml:3-15, tests/test_static.py:164-180
Dual-Python Architecture
A critical component of the build is the "Dual Python Architecture." The container maintains two distinct Python environments to satisfy conflicting compatibility requirements:
- System Python (Linux): Version 3.13+, used for
mt5linuxcompatibility and modern system-level tooling. - Wine Python (Windows): Version 3.12, installed inside the Wine prefix. This specific version is required for compatibility with
numpy 1.26.4, which is a strict requirement for the MetaTrader5 Python package.
Sources: README.md:43-55, tests/test_static.py:79-110
Python Version Specifications
| Environment | Python Version | Purpose |
|---|---|---|
| System (Debian) | 3.13 | mt5linux, Poetry, and CI/CD operations |
| Wine (Windows) | 3.12 | MetaTrader5 package, gRPC bridge, and NumPy 1.26.4 |
Sources: README.md:58-65, docker/compose.yaml:7-12
Build-Time Configuration
The build process is parameterized using ARG instructions in the Dockerfile, which are often overridden by the docker/compose.yaml file to ensure consistency across development and production environments.
The diagram shows how version configurations flow from the environment variables into the multi-stage Docker build process.
Sources: docker/compose.yaml:3-20, tests/test_static.py:182-200
Build Arguments and Components
The following versions are typically pinned during the build to ensure reproducibility:
- PYTHON_VERSION: 3.12 (Wine side)
- GRPCIO_VERSION: 1.76.0 (Required for modern gRPC stubs)
- NUMPY_VERSION: 1.26.4 (Wine compatibility)
- MT5_PYPI_VERSION: 5.0.5735
- WINE_MONO_VERSION: 10.4.0 (Replaces Mono for .NET support)
Sources: docker/compose.yaml:7-15, tests/test_static.py:85-115
Runtime Initialization and Setup
Unlike standard containers where all software is baked in, this project performs a "first-boot" initialization. This is handled by setup.sh and orchestrated by start.sh to avoid non-deterministic failures during BuildKit's concurrent stage scheduling.
Setup Sequence Logic
The setup sequence ensures the Wine environment is built reliably in a single isolated container instance before running the terminal.
Sources: docker/container/metatrader/setup.sh:80-165, docker/container/metatrader/start.sh:75-95
Critical Setup Functions
- unpack_config: Extracts
mt5-config.tar.gzif it exists in the/configvolume. - init_wine_prefix: Performs a one-time (~3-5 min) build of the Wine prefix, including Mono, Gecko, and Python. It uses a dedicated
Xvfbdisplay (:99) for headless installation. - install_mt5_terminal: Downloads
mt5setup.exeand runs it with/auto. It includes logic to detect the installedterminal64.exeand handle installer timeouts. - copy_bridge: Injects
bridge.py,mt5_pb2.py, andmt5_pb2_grpc.pyinto the Wine Pythonsite-packagesdirectory.
Sources: docker/container/metatrader/setup.sh:65-78, docker/container/metatrader/setup.sh:220-270, docker/container/metatrader/setup.sh:315-360
Dependency Management and Testing
The project uses Poetry for local dependency management and a specialized script, setup-dependencies.sh, to handle the mt5linux requirement across different environments.
Dependency Modes
- Development: Uses a local path dependency (
../mt5linux) configured viasetup-dependencies.sh. - Production/CI: Uses a Git reference (
https://github.com/marlonsc/mt5linux.git%60) as defined inpyproject.toml`.
Sources: scripts/setup-dependencies.sh:10-30, pyproject.toml:50-55
Static Validation
A comprehensive test suite in tests/test_static.py validates the build configuration without requiring a running container. These tests check:
- Consistency between
versions.env,Dockerfile, andcompose.yaml. - Shell script syntax and executable permissions.
- OCI label compliance.
- Protobuf gencode versions against the runtime pin.
Sources: tests/test_static.py:15-50, tests/test_static.py:118-140
Summary of Build Features
| Feature | Description | Source |
|---|---|---|
| Multi-Stage Build | Uses stages (base, wine-base, downloader, runtime) for efficiency. | test_static.py:186 |
| Headless VNC | Remote access via KasmVNC on port 3000. | README.md:75 |
| Auto-Login | Credentials provided via env vars generate startup.ini. | setup.sh:295 |
| Health Monitoring | health_monitor.sh provides auto-recovery for MT5 and gRPC. | README.md:120 |
| Zero-Touch Demo | Optional GUI automation to create demo accounts via open_demo_account.py. | README.md:165 |
This modular build and initialization system allows the mt5-docker project to deliver a professional, production-ready environment that abstracts the complexities of running Windows trading software on Linux.