Configuration & Settings

Relevant source files

The following files were used as context for generating this wiki page:

• mt5linux/settings.py
• mt5linux/constants.py
• DOCKER_COMPOSE_USAGE.md
• mt5linux/models.py
• mt5linux/utilities.py
• tests/constants.py

The mt5linux project utilizes a centralized configuration system designed for high availability and terminal resilience in Linux environments. The core of this system is the MT5Settings class, which serves as the single source of truth for all networking, retry logic, circuit breaker parameters, and transaction handling across the project.

The configuration architecture prioritizes automatic environment variable loading (using the MT5_ prefix) and provides isolated port mapping strategies for production, Docker-host access, and automated testing environments. This ensures that the MetaTrader 5 bridge can operate reliably within containerized workflows while maintaining strict isolation during CI/CD or local development.

Sources: mt5linux/settings.py:11-25, DOCKER_COMPOSE_USAGE.md:3-10

Configuration Hierarchy and Loading

The system follows a strict precedence hierarchy for loading configuration values, ensuring flexibility across different deployment stages.

1. Environment Variables: Variables prefixed with MT5_ (e.g., MT5_GRPC_PORT) take highest precedence.
2. Environment Files: Configuration is loaded from .env or .env.test files.
3. Defaults: Hardcoded defaults within the MT5Settings class.

Sources: mt5linux/settings.py:16-20, DOCKER_COMPOSE_USAGE.md:12-14

Network & Port Strategy

The project implements a multi-tier port strategy to resolve conflicts between internal container services, host-mapped access, and isolated test runs.

Port Mappings

Configuration Category	gRPC Port	VNC Port	Health Port	Usage Context
Internal (Container)	8001	3000	8002	Service-to-service inside Docker
Docker (Host)	38812	33000	38002	Direct access from the Linux host
Test (Isolated)	28812	23000	28002	Automated pytest execution

Sources: mt5linux/settings.py:48-69, mt5linux/constants.py:22-35

Resilience and Fault Tolerance

Resilience settings are critical for handling the unstable nature of gRPC connections over Wine. The system defines specific strategies for retries, backoff, and circuit breaking.

Retry Logic

The MT5Settings class provides methods to calculate exponential backoff with jitter to prevent "thundering herd" issues during server recovery.

• Standard Retry: Used for read-only operations or general API calls.
• Critical Retry: Used for order_send and order_check. These utilize a faster initial delay (0.1s vs 0.5s) to ensure quick recovery during volatile market conditions.

Sources: mt5linux/settings.py:126-160, mt5linux/utilities.py:539-555

Circuit Breaker Configuration

The CircuitBreaker utility uses settings to determine when to trip the circuit and block requests to a failing MT5 terminal.

Setting	Type	Default	Description
cb_threshold	int	5	Failures required to open the circuit
cb_recovery	float	30.0	Seconds to wait before attempting recovery
cb_half_open_max	int	3	Max requests allowed in half-open state

Sources: mt5linux/settings.py:86-90, mt5linux/constants.py:59-65

Transaction Handling and WAL

For state-changing operations, the configuration enables advanced tracking and persistence features to ensure idempotency.

Write-Ahead Log (WAL) Settings

The WAL persists order intent before transmission to prevent order loss during crashes.

• Path: wal_path defaults to ~/.mt5linux/wal.db.
• Retention: wal_retention_days defaults to 7 days for auto-cleanup of verified entries.

Sources: mt5linux/settings.py:112-117, mt5linux/utilities.py:1141-1155

Verification Logic

When a transaction returns an ambiguous status (e.g., TIMEOUT or CONNECTION_LOST), the settings dictate the verification window.

• Search Window: tx_verify_search_window_minutes (Default: 15) defines how far back to search in history for a matching request_id.
• Propagation Delay: tx_verify_propagation_delay (Default: 0.5s) allows the MT5 internal state to sync before verification occurs.

Sources: mt5linux/settings.py:96-107, mt5linux/utilities.py:990-1010

Global Constants and Enums

The MT5Constants class organizes business domain constants into namespaces. These are used to validate and constrain configuration values.

class MT5Constants:
    class Network:
        GRPC_PORT = 8001
        MAX_MESSAGE_SIZE = 50 * 1024 * 1024 # 50MB
    
    class Order:
        class OrderFilling(IntEnum):
            FOK = 0
            IOC = 1

Sources: mt5linux/constants.py:14-20, mt5linux/constants.py:228-235

Conclusion

The Configuration & Settings module provides the foundation for the mt5linux bridge's reliability. By centralizing logic in MT5Settings and using MT5Constants for domain-specific enums, the project ensures that resilience patterns like the Circuit Breaker and WAL are consistently applied. This architecture allows developers to tune performance and safety parameters through environment variables without modifying the core codebase.

Sources: mt5linux/settings.py:11-20, mt5linux/utilities.py:11-30