Docker Environments
Relevant source files
The following files were used as context for generating this wiki page:
Docker environments in the cyrus project provide isolated, reproducible contexts for running both the modern Rust-based rebuild and the original 1998 game. These environments ensure consistent behavior for automated agents and manual verification.
The project maintains two primary Docker configurations:
- Dev Environment: Runs the cyrus engine on a virtual display for automated testing and headless execution.
- Retro Environment: Runs the original Redguard executable under DOSBox-X for fidelity comparisons.
Sources: AGENTS.md:109-112
Environment Architecture
The Docker architecture separates the modern engine from the legacy environment. Automated agents use these containers to verify changes against the original game specification.
The diagram shows how both containers consume a shared game install to perform side-by-side execution or automated comparisons.
Sources: AGENTS.md:109-112, dev/docker/dev/entrypoint.sh
Dev Environment
The Dev environment facilitates running cyrus in a headless or virtualized graphical state. It uses a virtual frame buffer (Xvfb) to satisfy Bevy's windowing requirements without a physical monitor.
Virtual Display Setup
The entrypoint script initializes a virtual X11 server to support graphical execution in containerized environments.
- Display Initialization: The script starts
Xvfbon display:99. - Resolution Configuration: It sets a screen resolution of 1280x1024 with 24-bit color depth.
- Process Management: It executes the passed command (typically
cargo runor a test suite) within this X11 context.
Sources: dev/docker/dev/entrypoint.sh:3-5
Retro Environment
The Retro environment runs the original 1998 Redguard executable. This environment provides the ground truth for "Faithful" mode verification.
DOSBox-X Configuration
The environment uses a specific dosbox-x.conf to match the technical characteristics of the original game while enabling integration with modern tooling.
| Category | Setting | Value | Description |
|---|---|---|---|
| CPU | core | auto | Automated CPU core selection |
| CPU | cycles | max | Provides maximum performance for the engine |
| Video | vmemsize | 8 | 8MB Video memory |
| Storage | mount | c /redguard | Mounts the game install to the C drive |
Sources: dev/docker/retro/dosbox-x.conf:1-40
Execution Flow
The retro entrypoint automates the mounting and execution of the original game files.
The sequence shows the automated path from container start to original game execution.
Sources: dev/docker/retro/entrypoint.sh:4-7
Integration with Automated Agents
Automated agents rely on these environments to fulfill the project's "Hard Rules" regarding fidelity and verification.
- Fidelity Checks: Agents run the
retrocontainer to observe original behavior and thedevcontainer to verify the cyrus implementation matches. - Headless Verification: The dev container supports
cargo run -p cyrus -- --headless, allowing agents to verify logic without rendering overhead. - Resource Isolation: Containers ensure that the "read-only" status of the game install is maintained, as the engine facts are derived from the data without modifying the source.
Sources: AGENTS.md:18-30, AGENTS.md:144-147
Summary
Docker environments provide the infrastructure necessary for high-fidelity rebuild verification. By virtualizing the display for the modern engine and providing a configured DOSBox-X instance for the legacy engine, the project enables automated comparisons that ensure cyrus remains faithful to the original Redguard experience.