mtg_python_deckbuilder/DOCKER.md

Docker Guide

Spin up the MTG Python Deckbuilder inside containers. The image defaults to the Web UI; switch to the CLI/headless runner by flipping environment variables. All commands assume Windows PowerShell.

Build a Deck (Web UI)

• Build the image (first run only) and start the web service in detached mode:

docker compose up --build --no-deps -d web

• Open http://localhost:8080 to use the browser experience. First launch seeds data, downloads the latest card catalog, and tags cards automatically (WEB_AUTO_SETUP=1, WEB_TAG_PARALLEL=1, WEB_TAG_WORKERS=4 in docker-compose.yml).

• Stop or restart the service when you're done:

docker compose stop web
docker compose start web

• Prefer the public image? Pull and run it without building locally:

docker run --rm -p 8080:8080 `
  -v "${PWD}/deck_files:/app/deck_files" `
  -v "${PWD}/logs:/app/logs" `
  -v "${PWD}/csv_files:/app/csv_files" `
  -v "${PWD}/config:/app/config" `
  -v "${PWD}/owned_cards:/app/owned_cards" `
  mwisnowski/mtg-python-deckbuilder:latest

Shared volumes persist builds, logs, configs, and owned cards on the host.

Run a JSON Config

Use the homepage “Run a JSON Config” button or run the same flow in-container:

docker compose run --rm `
  -e APP_MODE=cli `
  -e DECK_MODE=headless `
  -e DECK_CONFIG=/app/config/deck.json `
  web

• APP_MODE=cli routes the entrypoint to the CLI menu.
• DECK_MODE=headless skips prompts and calls headless_runner.
• Mount JSON configs under config/ so both the UI and CLI can pick them up.

Override counts, theme tags, or include/exclude lists by setting the matching environment variables before running the container (see “Environment variables” below).

Initial Setup

The homepage “Initial Setup” tile appears when SHOW_SETUP=1 (enabled in compose). It re-runs:

1. Card downloads and color-filtered CSV generation.
2. Commander catalog rebuild (including multi-face merges).
3. Tagging and caching.

To force a rebuild from the host:

docker compose run --rm --entrypoint bash web -lc "python -m code.file_setup.setup"

Add --entrypoint bash ... "python -m code.scripts.refresh_commander_catalog" when you only need the commander catalog (with MDFC merge and optional compatibility snapshot).

Owned Library

Store .txt or .csv lists in owned_cards/ (mounted to /app/owned_cards). The Web UI uses them for:

• Owned-only or prefer-owned builds.
• The Owned Library management page (virtualized when WEB_VIRTUALIZE=1).
• Alternative suggestions that respect ownership.

Use /owned to upload files and export enriched lists. These files persist through the owned_cards volume.

Browse Commanders

SHOW_COMMANDERS=1 exposes the commander browser tile.

• Data lives in csv_files/commander_cards.csv.
• Refresh the catalog (including MDFC merges) from within the container:

docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.refresh_commander_catalog"

Pass --compat-snapshot if you also need an unmerged compatibility CSV under csv_files/compat_faces/.

Finished Decks

The Finished Decks page reads the deck_files/ volume for completed builds:

• Each run produces CSV, TXT, compliance JSON, and summary JSON sidecars.
• Locks and replace history persist per deck.
• Compare view can diff and export summaries.

Ensure the deck exports volume remains mounted so these artifacts survive container restarts.

Browse Themes

The Themes browser exposes the merged theme catalog with search, filters, and diagnostics.

• ENABLE_THEMES=1 keeps the selector visible.
• WEB_THEME_PICKER_DIAGNOSTICS=1 unlocks uncapped synergies, extra metadata, and /themes/metrics.
• Regenerate the catalog manually:

docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.build_theme_catalog"

Advanced options (e.g., EDITORIAL_* variables) live in .env.example.

Random Build

Enable the Surprise/Reroll flow by setting:

• RANDOM_MODES=1 to expose backend random endpoints.
• RANDOM_UI=1 to show the Random Build tile.
• Optional tunables: RANDOM_MAX_ATTEMPTS, RANDOM_TIMEOUT_MS, RANDOM_PRIMARY_THEME, RANDOM_SEED, and auto-fill flags.

Headless parity is available by pairing APP_MODE=cli with DECK_MODE=headless and the same random variables.

Diagnostics

SHOW_DIAGNOSTICS=1 unlocks /diagnostics for system summaries, feature flags, and performance probes. Highlights:

• /healthz returns {status, version, uptime_seconds} for external monitoring.
• Press v on pages with virtualized grids (when WEB_VIRTUALIZE=1) to toggle the range overlay.
• WEB_AUTO_ENFORCE=1 (optional) applies bracket enforcement automatically after each build.

View Logs

SHOW_LOGS=1 enables the logs tile and /logs interface:

• Tail the container log with filtering and copy-to-clipboard.
• /status/logs?tail=200 offers a lightweight JSON endpoint.
• Raw files live under logs/ on the host; rotate or archive them as needed.

Environment variables (Docker quick reference)

See .env.example for the full catalog. Common knobs:

Core mode and networking

Variable	Default	Purpose
APP_MODE	web	Switch between Web UI (web) and CLI (cli).
DECK_MODE	(unset)	headless auto-runs the headless builder when the CLI starts.
DECK_CONFIG	/app/config/deck.json	JSON config file or directory (auto-discovery).
HOST / PORT / WORKERS	0.0.0.0 / 8080 / 1	Uvicorn binding when APP_MODE=web.

Homepage visibility & UX

Variable	Default	Purpose
SHOW_SETUP	1	Show the Initial Setup card.
SHOW_LOGS	1	Enable the View Logs tile and endpoints.
SHOW_DIAGNOSTICS	1	Enable Diagnostics tools and overlays.
SHOW_COMMANDERS	1	Expose the commander browser.
ENABLE_THEMES	1	Keep the theme selector and themes explorer visible.
WEB_VIRTUALIZE	1	Opt-in to virtualized lists/grids for large result sets.
ALLOW_MUST_HAVES	1	Enable include/exclude enforcement in Step 5.
THEME	dark	Initial UI theme (system, light, or dark).

Random build controls

Variable	Default	Purpose
RANDOM_MODES	(unset)	Enable random build endpoints.
RANDOM_UI	(unset)	Show the Random Build homepage tile.
RANDOM_MAX_ATTEMPTS	5	Retry budget for constrained random rolls.
RANDOM_TIMEOUT_MS	5000	Per-attempt timeout in milliseconds.
RANDOM_PRIMARY_THEME / RANDOM_SECONDARY_THEME / RANDOM_TERTIARY_THEME	(blank)	Override theme slots for random runs.
RANDOM_SEED	(blank)	Deterministic seed.
RANDOM_AUTO_FILL	1	Allow automatic backfill of missing theme slots.

Automation & performance

Variable	Default	Purpose
WEB_AUTO_SETUP	1	Auto-run data setup when artifacts are missing or stale.
WEB_AUTO_REFRESH_DAYS	7	Refresh cards.csv if older than N days.
WEB_TAG_PARALLEL	1	Use parallel workers during tagging.
WEB_TAG_WORKERS	4	Worker count for parallel tagging.
WEB_AUTO_ENFORCE	0	Re-export decks after auto-applying compliance fixes.
WEB_THEME_PICKER_DIAGNOSTICS	1	Enable theme diagnostics endpoints.

Paths and data overrides

Variable	Default	Purpose
CSV_FILES_DIR	/app/csv_files	Point the app at an alternate dataset (e.g., test snapshots).
DECK_EXPORTS	/app/deck_files	Override where the web UI looks for exports.
OWNED_CARDS_DIR / CARD_LIBRARY_DIR	/app/owned_cards	Override owned library directory.
CARD_INDEX_EXTRA_CSV	(blank)	Inject a synthetic CSV into the card index for testing.

Advanced editorial and theme-catalog knobs (EDITORIAL_*, SPLASH_ADAPTIVE, etc.) are documented inline in docker-compose.yml and .env.example.

Shared volumes

Host path	Container path	Contents
deck_files/	/app/deck_files	CSV/TXT exports, summary JSON, compliance reports.
logs/	/app/logs	Application logs and taxonomy snapshots.
csv_files/	/app/csv_files	Card datasets, commander catalog, tagging flags.
config/	/app/config	JSON configs, bracket policy, card list overrides.
owned_cards/	/app/owned_cards	Uploaded inventory files for owned-only flows.

Maintenance commands

Run ad-hoc tasks by overriding the entrypoint:

# Theme catalog rebuild
docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.build_theme_catalog"

# Snapshot taxonomy (writes logs/taxonomy_snapshots/)
docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.snapshot_taxonomy"

# Preview the MDFC commander diff
docker compose run --rm --entrypoint bash web -lc "python -m code.scripts.preview_dfc_catalog_diff"

Use the --compat-snapshot or other script arguments as needed.

Troubleshooting

• Container starts but UI stays blank: check /healthz and /logs (enable with SHOW_LOGS=1), then inspect the logs/ volume.
• Files missing on the host: ensure the host directories exist before starting Compose; Windows will create empty folders if the path is invalid.
• Long first boot: dataset downloads and tagging can take several minutes the first time. Watch progress at /setup.
• Random build hangs: lower RANDOM_MAX_ATTEMPTS or raise RANDOM_TIMEOUT_MS, and confirm your theme overrides are valid slugs via /themes/.
• Commander catalog outdated: rerun the refresh command above or delete csv_files/.tagging_complete.json to force a full rebuild on next start.