Volume & Data Directory Management
Relevant source files
The following files were used as context for generating this wiki page:
Volume and data directory management in the mt5-docker project is centered around providing a persistent, predictable environment for MetaTrader 5 (MT5) running within a Wine-based Linux container. The system ensures that critical trading data, including the Wine prefix, terminal configurations, Expert Advisors (EAs), and logs, survive container restarts and updates.
The primary mechanism for persistence is the /config volume, which serves as the root for all persistent state. This directory houses the Wine environment, the MT5 installation, and application-specific metadata such as auto-login configurations and build markers.
Sources: README.md:273-281, docker/compose.yaml:23-25, tests/constants.py:236-237
Core Volume Architecture
The system utilizes Docker volumes to map host-side storage to specific internal container paths. The architecture distinguishes between the persistent configuration area and the read-only staging area.
Primary Volume Mounts
| Path | Mode | Description |
|---|---|---|
/config | Persistent | Contains the .wine prefix, MT5 data, and environment settings. |
/opt/mt5-staging | Staging | Internal directory used for pre-downloaded installers and templates during build/setup. |
/data | Optional | Can be used for pre-configured archives to accelerate first-run startup. |
Sources: README.md:273-281, docker/compose.yaml:45, tests/constants.py:236-237
Data Flow Diagram
The following diagram illustrates how data is initialized and persisted between the staging area and the persistent volume during the container lifecycle.
The diagram shows the transition from build-time staging to runtime persistence.
Sources: docker/container/metatrader/setup.sh:84-105, README.md:281-285
Wine Prefix & Filesystem Structure
The Wine prefix (the simulated Windows environment) is stored at /config/.wine. This structure is critical for MT5's operation, as it mimics the Windows C: drive layout.
Internal MQL5 Layout
For developers, the most relevant paths are located within the MT5 installation directory inside Wine. These directories allow for the placement of custom trading scripts without restarting the container.
- EAs/Indicators:
/config/.wine/drive_c/Program Files/MetaTrader 5/MQL5/ - MT5 Logs:
/config/.wine/drive_c/Program Files/MetaTrader 5/logs/ - Startup Config:
/config/.wine/drive_c/MT5Config/startup.ini
Sources: README.md:213-219, docker/container/metatrader/open_demo_account.py:46-51
Initialization & Idempotency Logic
To avoid redundant installations or corrupting data during partial container boots, the system employs an idempotency logic based on marker files within the volume.
Build Markers
.build-complete: Located at$WINEPREFIX/.build-complete. This file is only written after a successful first-boot setup (Wine prefix init, Python installation, and gRPC package setup). If the directory exists but this marker is missing, the setup script assumes a corrupted state and rebuilds from scratch.DEPS_MARKER: Used to verify that Wine-specific configurations (like the Windows version registry settings) have been applied.
Sources: docker/container/metatrader/setup.sh:84-91, docker/container/metatrader/setup.sh:180-185
Setup Sequence Flow
Account Metadata Management
The system manages account data via two primary configuration files stored in the persistent volume:
1. startup.ini
This file is used by the MT5 terminal to perform automatic login on launch. It contains credentials such as Login, Password, and Server. It is generated by the setup.sh script if environment variables are provided, or by the open_demo_account.py script during zero-touch provisioning.
Sources: docker/container/metatrader/setup.sh:276-295, docker/container/metatrader/open_demo_account.py:302-317
2. auto_demo.json
When MT5_AUTO_CREATE_DEMO is enabled, the system stores account metadata in this file. It serves as a success marker and prevents the redundant creation of demo accounts.
| Field | Type | Description |
|---|---|---|
login | String | The provisioned account number. |
server | String | The broker server name. |
login_confirmed | Boolean | Verification that the terminal successfully authorized. |
credentials_persisted | Boolean | Whether Login/Password were saved to startup.ini. |
Sources: docker/container/metatrader/open_demo_account.py:346-354, tests/test_static.py:656-675
Volume Permission & Security
The container runs with specific user and group IDs (PUID and PGID, default 911) to ensure compatibility with the host filesystem. The compose.yaml explicitly sets these permissions for the config_data volume mount to prevent permission-denied errors when Wine attempts to write to its prefix.
Sources: docker/compose.yaml:25, README.md:267-268
Conclusion
Volume and directory management in this project ensures that the heavy Wine environment and MT5 installation are persistent and resilient. By leveraging a single /config volume and a robust marker-based initialization strategy, the system provides a stable platform for both manual trading via VNC and automated trading via the gRPC bridge.