mtg_python_deckbuilder/DOCKER.md

Docker Usage Guide for MTG Deckbuilder

Quick Start (Recommended)

Linux/Remote Host (Interactive Applications)

# Make scripts executable (one time only)
chmod +x quick-start.sh run-docker-linux.sh

# Simplest method - just run this:
./quick-start.sh

# Or use the full script with more options:
./run-docker-linux.sh compose

Windows (PowerShell)

# Run with Docker Compose
.\run-docker.ps1 compose

Important: Interactive Applications & Docker Compose

Your MTG Deckbuilder is an interactive application that uses menus and requires keyboard input. This creates special requirements:

✅ What Works for Interactive Apps:

• docker run -it (manual)
• docker-compose run (recommended)
• ./quick-start.sh (easiest)

❌ What Doesn't Work:

• docker-compose up (runs in background, no interaction)
• Running without -it flags

Why the Difference?

• docker-compose up: Starts services in the background, doesn't attach to your terminal
• docker-compose run: Creates a new container and attaches to your terminal for interaction

Manual Docker Commands

Windows PowerShell

# Build the image
docker build -t mtg-deckbuilder .

# Run with volume mounting for file persistence
docker run -it --rm `
    -v "${PWD}/deck_files:/app/deck_files" `
    -v "${PWD}/logs:/app/logs" `
    -v "${PWD}/csv_files:/app/csv_files" `
    mtg-deckbuilder

Linux/macOS/Git Bash

# Build the image
docker build -t mtg-deckbuilder .

# Run with volume mounting for file persistence
docker run -it --rm \
    -v "$(pwd)/deck_files:/app/deck_files" \
    -v "$(pwd)/logs:/app/logs" \
    -v "$(pwd)/csv_files:/app/csv_files" \
    mtg-deckbuilder

File Persistence Explained

The key to saving your files is volume mounting. Here's what happens:

Without Volume Mounting (Bad)

• Files are saved inside the container
• When container stops, files are lost forever
• Example: docker run -it mtg-deckbuilder ❌

With Volume Mounting (Good)

• Files are saved to your local directories
• Files persist between container runs
• Local directories are "mounted" into the container
• Example: docker run -it -v "./deck_files:/app/deck_files" mtg-deckbuilder ✅

Directory Structure After Running

After running the Docker container, you'll have these local directories:

mtg_python_deckbuilder/
├── deck_files/          # Your saved decks (CSV and TXT files)
├── logs/               # Application logs
├── csv_files/          # Card database files
└── ...

Troubleshooting

Files Still Not Saving?

1. Check directory creation: The helper scripts automatically create the needed directories
2. Verify volume mounts: Look for -v flags in your docker run command
3. Check permissions: Make sure you have write access to the local directories

Starting Fresh

# Windows - Clean up everything
.\run-docker.ps1 clean

# Or manually
docker-compose down
docker rmi mtg-deckbuilder

Container Won't Start

1. Make sure Docker Desktop is running
2. Try rebuilding: .\run-docker.ps1 build
3. Check for port conflicts
4. Review Docker logs: docker logs mtg-deckbuilder

Helper Script Commands

Windows PowerShell

.\run-docker.ps1 build     # Build the Docker image
.\run-docker.ps1 run       # Run with manual volume mounting
.\run-docker.ps1 compose   # Run with Docker Compose (recommended)
.\run-docker.ps1 clean     # Clean up containers and images
.\run-docker.ps1 help      # Show help

Linux/macOS

./run-docker.sh build     # Build the Docker image
./run-docker.sh run       # Run with manual volume mounting
./run-docker.sh compose   # Run with Docker Compose (recommended)
./run-docker.sh clean     # Clean up containers and images
./run-docker.sh help      # Show help

Why Docker Compose is Recommended

Docker Compose offers several advantages:

1. Simpler commands: Just docker-compose up
2. Configuration in file: All settings stored in docker-compose.yml
3. Automatic cleanup: Containers are removed when stopped
4. Consistent behavior: Same setup every time

Verifying File Persistence

After running the application and creating/saving files:

1. Exit the Docker container
2. Check your local directories:

   ls deck_files    # Should show your saved deck files
   ls logs         # Should show log files
   ls csv_files    # Should show card database files
   

3. Run the container again - your files should still be there!