mwisnowski/mtg-python-deckbuilder repository overview

⁠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

Then open http://localhost:8080⁠

Volumes are the same as the CLI service, so deck exports/logs/configs persist in your working folder. The app serves a favicon at /favicon.ico and exposes a health endpoint at /healthz. Compare view offers a Copy summary button to copy a plain-text diff of two runs. The sidebar has a subtle depth shadow for clearer separation.

Web UI feature highlights:

• Locks: Click a card or the lock control in Step 5; locks persist across reruns.
• Replace: Enable Replace in Step 5, click a card to open Alternatives (filters include Owned-only), then choose a swap.
• Permalinks: Copy a permalink from Step 5 or a Finished deck; paste via “Open Permalink…” to restore.
• Compare: Use the Compare page from Finished Decks; quick actions include Latest two and Swap A/B.

Virtualized lists and lazy images (opt‑in)

• Set WEB_VIRTUALIZE=1 to enable virtualization in Step 5 grids/lists and the Owned library for smoother scrolling on large sets.
• Example (Compose):

  services:
      web:
          environment:
              - WEB_VIRTUALIZE=1
  

  Copy
• Example (Docker Hub):

  docker run --rm -p 8080:8080 `
      -e WEB_VIRTUALIZE=1 `
      -v "${PWD}/deck_files:/app/deck_files" `
      -v "${PWD}/logs:/app/logs" `
      -v "${PWD}/csv_files:/app/csv_files" `
      -v "${PWD}/owned_cards:/app/owned_cards" `
      -v "${PWD}/config:/app/config" `
  -e SHOW_DIAGNOSTICS=1 ` # optional: enables diagnostics tools and overlay
  mwisnowski/mtg-python-deckbuilder:latest `
      bash -lc "cd /app && uvicorn code.web.app:app --host 0.0.0.0 --port 8080"
  

  Copy

⁠Diagnostics and logs (optional)

Enable internal diagnostics and a read-only logs viewer with environment flags.

• SHOW_DIAGNOSTICS=1 — adds a Diagnostics nav link and /diagnostics tools
• SHOW_LOGS=1 — enables /logs and /status/logs?tail=200

Per-face MDFC snapshot (opt-in)

• DFC_PER_FACE_SNAPSHOT=1 — write merged MDFC face metadata to logs/dfc_per_face_snapshot.json; disable parallel tagging (WEB_TAG_PARALLEL=0) if you need the snapshot during setup.
• DFC_PER_FACE_SNAPSHOT_PATH=/app/logs/custom_snapshot.json — optional path override for the snapshot artifact.

When enabled:

• /logs supports an auto-refresh toggle with interval, a level filter (All/Error/Warning/Info/Debug), and a Copy button to copy the visible tail.
• /status/sys returns a simple system summary (version, uptime, UTC server time, and feature flags) and is shown on the Diagnostics page when SHOW_DIAGNOSTICS=1.
• Virtualization overlay: press v on pages with virtualized grids to toggle per-grid overlays and a global summary bubble.

Compose example (web service):

environment:
    - SHOW_LOGS=1
    - SHOW_DIAGNOSTICS=1

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

⁠MDFC merge rollout (staging)

The web service now runs the MDFC merge by default. Set DFC_COMPAT_SNAPSHOT=1 on the web service when you need the legacy unmerged compatibility snapshot (csv_files/compat_faces/). Combine this with python -m code.scripts.refresh_commander_catalog --compat-snapshot inside the container to regenerate the commander files before smoke testing.

Follow the QA steps in docs/qa/mdfc_staging_checklist.md after toggling the flag.

Compose example:

services:
    web:
        environment:
            - DFC_COMPAT_SNAPSHOT=1

Verify the refresh inside the container:

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

Downstream consumers can diff csv_files/compat_faces/commander_cards_unmerged.csv against historical exports during the staging window.

⁠Setup speed: parallel tagging (Web)

First-time setup or stale data triggers card tagging. The web service uses parallel workers by default.

⁠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.
• Dual-commander support is feature-flagged: set ENABLE_PARTNER_MECHANICS=1 and pass --secondary-commander or --background (mutually exclusive) to layer partners/backgrounds into headless runs; Partner With and Doctor/Doctor’s Companion pairings auto-resolve (with opt-out), and --dry-run echoes the resolved pairing for verification.
• Partner suggestions share the same dataset for headless and web flows; set ENABLE_PARTNER_SUGGESTIONS=1 (and ensure config/analytics/partner_synergy.json exists) to expose ranked pairings in the UI and API.

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.

⁠Budget Mode

Enable cost-aware deck building with ENABLE_BUDGET_MODE=1 (default). A per-card budget ceiling is entered in the New Deck modal.

• Soft enforcement only: cards above the ceiling are filtered from the selection pool, but no card is hard-rejected from the final result. The build summary flags over-budget cards for review and provides a per-category price breakdown.
• BUDGET_POOL_TOLERANCE (default 0.15) sets fractional headroom above the ceiling before exclusion (e.g. 0.15 = 15% overhead). Read at build time; not surfaced in the diagnostics panel.
• Price data comes from Scryfall bulk data cached locally. PRICE_LAZY_REFRESH=1 (default) refreshes stale per-card prices in the background. PRICE_AUTO_REFRESH=1 rebuilds the full cache daily at 01:00 UTC.
• PRICE_STALE_WARNING_HOURS (default 24) controls when a cached price shows a stale indicator. Set to 0 to disable.
• Price breakdown is included in build summary panels and exported summary JSON.

⁠Include / Exclude Lists

Set ALLOW_MUST_HAVES=1 (default) to enable include/exclude enforcement.

• SHOW_MUST_HAVE_BUTTONS=1 surfaces the Must Include and Must Exclude buttons and quick-add UI in Step 5 (hidden by default).
• Cards in Must Include are always added first. Cards in Must Exclude are never selected.
• Lists can also be supplied in JSON configs via the must_include and must_exclude keys.
• Priority: exclude > include > budget filter > bracket filter.

⁠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

⁠Partner mechanics & suggestions

⁠Homepage visibility & UX

⁠Random build controls

⁠Automation & performance

⁠Paths and data overrides

⁠Supplemental themes

⁠Random rate limiting (optional)

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

⁠Shared volumes

⁠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.