KasmVNC Web Interface
Relevant source files
The following files were used as context for generating this wiki page:
The KasmVNC Web Interface provides a high-performance, browser-based remote access layer for MetaTrader 5 (MT5) running within the Docker container. Based on the KasmVNC project and the LinuxServer KasmVNC Base Image, this interface allows users to interact with the MT5 GUI without requiring a native VNC client.
Sources: README.md:10-14, README.md:43-43
Architecture and Integration
The KasmVNC interface operates by hosting a headless Xvfb server and exposing the desktop session over HTTP/HTTPS on port 3000. It is integrated into the container via the LinuxServer.io base image, which manages the web server and VNC translation layer.
Headless Rendering and Virtual Desktops
To ensure the MT5 GUI renders correctly in a headless environment, the system utilizes Wine's "virtual desktop" mode. Without explorer /desktop=, MT5 menus and dialog boxes may render as black or fail to display correctly under Xvfb. This mode is critical for both manual user interaction and automated GUI operations.
Sources: tests/test_static.py:532-538, docker/container/metatrader/open_demo_account.py:32-34
User Access Flow
The following diagram illustrates how a user accesses the MetaTrader 5 interface through the KasmVNC layer:
The interface translates standard browser inputs (mouse clicks, keyboard events) into X11 events for the Wine environment.
Sources: README.md:143-145, docker/compose.yaml:31-31
Configuration and Deployment
The web interface is primarily configured through environment variables and port mappings in the Docker deployment.
Network Configuration
KasmVNC is exposed by default on port 3000. This must be mapped in the container runtime to be accessible from the host.
| Port | Protocol | Default | Description |
|---|---|---|---|
| 3000 | TCP/HTTP | 3000 | Main KasmVNC web interface access port. |
Sources: README.md:214-214, docker/compose.yaml:31-31, tests/constants.py:270-272
Permissions and Identity
The interface respects standard LinuxServer.io permission variables to ensure the persistent config volume remains accessible.
| Variable | Default | Description |
|---|---|---|
PUID | 911 | User ID for file permissions and KasmVNC process. |
PGID | 911 | Group ID for file permissions and KasmVNC process. |
VNC_PASSWORD | - | Password for securing the web interface access. |
Sources: README.md:204-205, README.md:261-264
GUI Automation via KasmVNC Display
The presence of the KasmVNC-managed Xvfb display enables "Zero-Touch" automation. The project includes a specialized script, open_demo_account.py, which uses xdotool to drive the MT5 GUI directly on the display used by the web interface.
Automation Logic
- Window Discovery: Scans the display for windows named "MetaTrader" or "Wine Desktop".
- Interaction: Sends calibrated clicks and keystrokes to specific XY coordinates (e.g.,
FILE_MENU_XYat 22, 42). - Coordination: Uses
xclipto interact with the system clipboard for credential capture.
Display Calibration
The automation is calibrated for a standard 1024x768 resolution, which is the default for the KasmVNC desktop in this container.
| UI Element | Default XY Coordinate | Environment Variable Override |
|---|---|---|
| File Menu | 22, 42 | MT5_DEMO_FILE_MENU_XY |
| Open Account | 85, 344 | MT5_DEMO_OPEN_ACCOUNT_MENU_XY |
| Next Button | 714, 636 | MT5_DEMO_NEXT_XY |
| Copy Info Link | 405, 489 | MT5_DEMO_COPY_INFO_XY |
Sources: docker/container/metatrader/open_demo_account.py:65-80
Troubleshooting the Web Interface
Standard checks for the KasmVNC interface include verifying port exposure and container health.
- Port Check: Ensure port 3000 is not blocked by a host firewall.
- Health Status: The container health check monitors the gRPC bridge (port 8001), but if KasmVNC fails, the MT5 GUI will not render properly, potentially impacting automation.
- Logs: KasmVNC logs are aggregated into the standard Docker container logs.
Sources: tests/test_runtime.py:91-118, docker/compose.yaml:85-92
Conclusion
The KasmVNC Web Interface serves as the primary visual entry point for the MetaTrader 5 Docker environment. By leveraging Wine's virtual desktop and a headless Xvfb server, it provides both a manual management console and a stable environment for GUI-based automation tasks like account provisioning.