Zero-Touch Demo Provisioning
Relevant source files
The following files were used as context for generating this wiki page:
Zero-Touch Demo Provisioning is an automated system designed to create and authorize MetaQuotes demo accounts within the MetaTrader 5 (MT5) Docker environment without manual intervention. This feature leverages GUI automation via xdotool on a headless Xvfb display to drive the terminal's "Open an Account" wizard. Sources: README.md:143-145, docker/container/metatrader/open_demo_account.py:1-10
The system is triggered during the container boot sequence when no explicit credentials (MT5_LOGIN) are provided and the MT5_AUTO_CREATE_DEMO environment variable is enabled. It ensures persistence by capturing generated passwords and writing them to the terminal's configuration, allowing the demo account to survive container restarts. Sources: README.md:146-153, docker/container/metatrader/open_demo_account.py:12-16
Architecture and Logic Flow
The provisioning logic resides in a dedicated Python script that interacts with the MT5 terminal running under Wine. It uses a combination of window management tools, clipboard monitoring, and log parsing to verify success. Sources: docker/container/metatrader/open_demo_account.py:35-50
Provisioning Workflow
The following diagram illustrates the sequence of operations performed during the zero-touch provisioning process.
The process starts by verifying if the terminal is already logged in or if a confirmed auto_demo.json exists to maintain idempotency. Sources: docker/container/metatrader/open_demo_account.py:535-555
Verification Mechanisms
Unlike OCR-based solutions, this system uses authoritative sources to verify account creation:
- Terminal Logs: Decodes UTF-16-LE logs to find "new demo account 'NNNN' opened" and "'NNNN': authorized" markers. Sources: docker/container/metatrader/open_demo_account.py:155-165, tests/test_static.py:465-475
- Clipboard Capture: Uses
xclipto grab registration info from the MT5 "Copy to clipboard" link on the final wizard page. Sources: docker/container/metatrader/open_demo_account.py:382-395 - Window Titles: Uses
xdotoolto check for account numbers in the window title as a fast fallback. Sources: docker/container/metatrader/open_demo_account.py:139-145
Components and Data Structures
Configuration and Calibration
The automation relies on root-window pixel coordinates calibrated for a 1024x768 display. Sources: docker/container/metatrader/open_demo_account.py:54-55
| Coordinate Name | Default (X, Y) | Description |
|---|---|---|
FILE_MENU_XY | (22, 42) | Clicks the 'File' menu in the MT5 terminal. |
OPEN_ACCOUNT_MENU_XY | (85, 344) | Selects 'Open an Account' from the dropdown. |
COMPANY_ROW_XY | (300, 271) | Selects 'MetaQuotes Ltd.' from the broker list. |
NEXT_XY | (714, 636) | Clicks the 'Next' button in the wizard. |
COPY_INFO_XY | (405, 489) | Clicks the link to copy credentials to clipboard. |
Sources: docker/container/metatrader/open_demo_account.py:70-82
Persistence Models
The system manages two primary files to ensure account stability:
- startup.ini: Stores
Login,Password, andServerunder the[Common]section. MT5 re-reads this on every boot to perform auto-authorization. Sources: docker/container/metatrader/open_demo_account.py:408-430 - auto_demo.json: A JSON marker indicating successful provisioning. Sources: docker/container/metatrader/open_demo_account.py:441-450
{
"login": "12345678",
"server": "MetaQuotes-Demo",
"email": "auto+uuid@example.com",
"created_at": "2023-10-27T10:00:00Z",
"login_confirmed": true,
"credentials_persisted": true
}
Sources: docker/container/metatrader/open_demo_account.py:441-449
Service Integration
The provisioning logic is integrated into the svc-mt5server S6-overlay service. This service ensures that the gRPC bridge only attaches after a successful login or provisioning event. Sources: tests/test_static.py:650-660
Configuration Options
Provisioning behavior is controlled via environment variables defined in the Docker Compose file or .env. Sources: docker/compose.yaml:63-65
| Variable | Default | Description |
|---|---|---|
MT5_AUTO_CREATE_DEMO | 0 | Set to 1 to enable zero-touch provisioning. |
MT5_DEMO_SERVER | MetaQuotes-Demo | The broker server for the demo account. |
MT5_DEMO_PERSIST_CREDS | 1 | Capture password and update startup.ini. |
MT5_DEMO_WINDOW_WAIT | 120 | Max seconds to wait for MT5 window to appear. |
MT5_DEMO_LOGIN_WAIT | 60 | Max seconds to wait for authorization logs. |
Sources: docker/container/metatrader/open_demo_account.py:38-51, docker/compose.yaml:63-65
Error Handling and Idempotency
The system implements a "fail-loud" design. If the wizard fails to produce an authorized login or if the generated password cannot be captured when persistence is required, the script exits with a non-zero code. This prevents the container from reporting a "healthy" status if the terminal is not actually authorized. Sources: README.md:154-158, tests/test_static.py:605-615
Idempotency is maintained by the confirmed_result_login() function, which checks if the currently active terminal login matches the one stored in auto_demo.json. If they match, the provisioning script exits immediately without driving the GUI. Sources: docker/container/metatrader/open_demo_account.py:504-520
Zero-Touch Demo Provisioning provides a reliable, automated path for spinning up functional MetaTrader 5 environments for testing and development without requiring pre-existing broker credentials. By combining GUI automation with log-based verification and configuration persistence, it ensures that the resulting environment is stable across container lifecycles.