Wine to Native migration

Safety rules

Never point Native at Wine's live volumes. Never use docker compose down -v on the Wine project.

• The migration helper defaults to a dry-run.
• Run the wrapper from a complete project checkout containing both Compose files and the scripts/ directory.
• Apply stops Wine itself and proves no running container still uses the source volume.
• The helper never deletes the source.
• Apply creates a mode-0600 Wine rollback archive.
• Native uses separate, initially empty volumes.

1. Review the dry-run

Run this from the existing Wine project directory while Wine is still running:

./scripts/migrate-compose-wine-to-native.sh plan

The wrapper reads both Compose files, discovers the project-scoped save volumes, validates game_0.db, and prints the source hash. It does not create the Native volume or stop Wine during the plan.

2. Apply the cutover

Do not stop Wine manually first. The wrapper must own the stop and prove that no running container still uses the source volume.

./scripts/migrate-compose-wine-to-native.sh apply

Apply rechecks the source hash, creates isolated Native volumes, writes a protected rollback archive under .conan-migration/, snapshots SQLite, starts Native, and waits for Docker health. A failed health check automatically stops Native and restarts Wine.

If the original project used a custom Compose name, add --project-name NAME to every command.

3. Start and verify Native

• Database integrity is ok.
• A2S returns the expected server name and map.
• RCON works when enabled.
• The exact Workshop dependency set is active.
• Players see their characters, clans, buildings, and inventories.
• At least one save cycle completes before cleanup is considered.

Rollback

If Native validation fails—or whenever you want to return before acceptance—run the explicit rollback. It stops Native and restarts Wine against the unchanged original volume. The Native volume and archive stay available for diagnosis.

./scripts/migrate-compose-wine-to-native.sh rollback