Quick Start Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides the necessary steps to deploy and configure the MetaTrader5 (MT5) Docker environment. The system facilitates running MT5 within an isolated Linux container using Wine, providing remote access via KasmVNC and a gRPC-based bridge for Python control.
The architecture relies on a dual-Python setup (3.13 for the system and 3.12 for Wine compatibility) to ensure optimal performance of the mt5linux bridge and MetaTrader 5 terminal operations. Users can choose between manual login via the VNC interface or automated headless provisioning for demo accounts.
Sources: README.md:10-30, docker/container/metatrader/start.sh:15-35
Prerequisites
Before deployment, ensure the host system meets the following requirements:
- Docker & Docker Compose: Installed and configured.
- Architecture: x86_64/amd64 hosts only.
- Python: >= 3.13 for system-level operations.
- Connectivity: Required for initial downloads of Wine components and MT5 terminal.
Sources: README.md:86-95
Rapid Deployment
The project includes a Makefile to automate the setup, testing, and execution phases.
# Clone the repository
git clone https://github.com/marlonsc/mt5-docker
cd mt5-docker
# Initialize the development environment and .env file
make setup
# Build and launch the container
make build
make run
Sources: README.md:97-111
Manual Docker Execution
If not using the Makefile, use the following standard Docker commands:
# Build the image
docker build -f docker/Dockerfile -t marlonsc/mt5-docker:debian docker/
# Run the container with necessary port mappings
docker run -d -p 3000:3000 -p 8001:8001 -v config:/config marlonsc/mt5-docker:debian
Sources: README.md:143-151
Configuration Management
Configuration is handled primarily through environment variables defined in a .env file or within docker-compose.yaml.
Essential Environment Variables
| Variable | Default | Description |
|---|---|---|
MT5_LOGIN | - | MetaTrader 5 account number for auto-login. |
MT5_PASSWORD | - | Account password. |
MT5_SERVER | MetaQuotes-Demo | Broker server address. |
MT5_AUTO_CREATE_DEMO | 0 | Set to 1 for headless "Open an Account" wizard. |
ENABLE_WIN_DOTNET | 1 | Installs .NET Framework 4.8 via Wine. |
AUTO_RECOVERY_ENABLED | 1 | Enables automatic restart of failed services. |
Sources: README.md:278-300, docker/compose.yaml:49-65
Zero-Touch Demo Provisioning
When MT5_AUTO_CREATE_DEMO=1 is set and MT5_LOGIN is empty, the system uses xdotool to automate the MT5 GUI wizard.
The wizard verifies the account creation by reading UTF-16 encoded terminal logs to confirm authorization before flagging the process as successful.
Sources: docker/container/metatrader/open_demo_account.py:35-70, README.md:189-205
Service Architecture and Lifecycle
The container uses s6-overlay for process supervision. The startup sequence is managed by start.sh, which triggers setup.sh for one-time initialization.
Initialization Flow
- Environment Export:
start.shexports paths and version constants. - Wine Prefix Construction:
setup.shbuilds the Wine prefix, installs Mono, Gecko, and Wine-side Python. - MT5 Installation: The MT5 terminal is downloaded and installed silently.
- Bridge Deployment: The gRPC bridge and protocol buffers are copied to the Wine site-packages.
- Supervision: S6-overlay starts the terminal and the gRPC server.
External Access and Ports
The container exposes specific ports for different interaction methods:
| Port | Protocol | Usage |
|---|---|---|
3000 | HTTP | KasmVNC interface (Web Browser Access). |
8001 | TCP | gRPC Bridge (Remote Python Control via mt5linux). |
8002 | TCP | Health check endpoint. |
Sources: docker/compose.yaml:31-33, tests/constants.py:175-180
Python Integration Example
Once the container is running, use mt5linux to control the terminal programmatically:
from mt5linux import MetaTrader5
# Connect to the Docker container
mt5 = MetaTrader5(host='localhost', port=8001)
mt5.initialize()
# Retrieve terminal version
print(mt5.version())
# Fetch symbol information
tick = mt5.symbol_info_tick("EURUSD")
print(f"Bid: {tick.bid}, Ask: {tick.ask}")
Sources: README.md:243-260
Conclusion
The mt5-docker project provides a robust, production-ready environment for automated trading. By leveraging Docker and Wine, it overcomes traditional OS limitations while maintaining high-performance Python connectivity through its gRPC bridge. The dual-stage setup ensures that all dependencies, from .NET Framework for EAs to specific NumPy versions, are correctly managed for stability.