###################################################################### # MTG Python Deckbuilder – Environment Variables Reference # # Copy this file to `.env` and uncomment the lines you want to override. # All lines are commented so copying it is safe; defaults apply otherwise. ###################################################################### ############################ # Core Application Modes ############################ # DECK_MODE=headless # headless|auto|. When set to 'headless' (or 'auto'), runs non-interactive build on start (CLI entrypoint). # APP_MODE=web # (Not explicitly set in dockerhub compose; uncomment to force.) # HOST=0.0.0.0 # Uvicorn bind host (only when APP_MODE=web). # PORT=8080 # Uvicorn port. # WORKERS=1 # Uvicorn worker count. APP_VERSION=v3.0.1 # Matches dockerhub compose. ############################ # Theming ############################ THEME=system # system|light|dark (initial default; user preference persists in browser). ############################ # Paths & Directories (override discovery) ############################ # DECK_CONFIG=/app/config/deck.json # File OR directory. File: run that config. Dir: discover JSON configs. CLI>ENV precedence. # DECK_EXPORTS=/app/deck_files # Where finished deck exports are read by Web UI. # OWNED_CARDS_DIR=/app/owned_cards # Preferred directory for owned inventory uploads. # CARD_LIBRARY_DIR=/app/owned_cards # Back-compat alias for OWNED_CARDS_DIR. # CSV_FILES_DIR=/app/csv_files # Override CSV base dir (DEPRECATED v3.0.0+, use CARD_FILES_* instead) # CARD_INDEX_EXTRA_CSV= # Inject an extra CSV into the card index for testing # Parquet-based card files (v3.0.0+) # CARD_FILES_DIR=card_files # Base directory for Parquet files (default: card_files) # CARD_FILES_RAW_DIR=card_files/raw # Raw MTGJSON Parquet files (default: card_files/raw) # CARD_FILES_PROCESSED_DIR=card_files/processed # Processed/tagged Parquet files (default: card_files/processed) # Legacy CSV compatibility (v3.0.0 only, removed in v3.1.0) # LEGACY_CSV_COMPAT=0 # Set to 1 to enable CSV fallback when Parquet loading fails ############################ # Web UI Feature Flags ############################ SHOW_SETUP=1 # dockerhub: SHOW_SETUP="1" SHOW_LOGS=1 # dockerhub: SHOW_LOGS="1" SHOW_DIAGNOSTICS=1 # dockerhub: SHOW_DIAGNOSTICS="1" ENABLE_THEMES=1 # dockerhub: ENABLE_THEMES="1" ENABLE_CUSTOM_THEMES=1 # dockerhub: ENABLE_CUSTOM_THEMES="1" USER_THEME_LIMIT=8 # dockerhub: USER_THEME_LIMIT="8" ENABLE_PWA=0 # dockerhub: ENABLE_PWA="0" ENABLE_PRESETS=0 # dockerhub: ENABLE_PRESETS="0" WEB_VIRTUALIZE=1 # dockerhub: WEB_VIRTUALIZE="1" ALLOW_MUST_HAVES=1 # dockerhub: ALLOW_MUST_HAVES="1" SHOW_MUST_HAVE_BUTTONS=0 # dockerhub: SHOW_MUST_HAVE_BUTTONS="0" (set to 1 to surface must include/exclude buttons) WEB_THEME_PICKER_DIAGNOSTICS=1 # dockerhub: WEB_THEME_PICKER_DIAGNOSTICS="1" ENABLE_CARD_DETAILS=1 # dockerhub: ENABLE_CARD_DETAILS="1" SIMILARITY_CACHE_ENABLED=1 # dockerhub: SIMILARITY_CACHE_ENABLED="1" SIMILARITY_CACHE_PATH="card_files/similarity_cache.parquet" # Path to Parquet cache file ENABLE_BATCH_BUILD=1 # dockerhub: ENABLE_BATCH_BUILD="1" (enable Build X and Compare feature) ############################ # Partner / Background Mechanics ############################ # HEADLESS_EXPORT_JSON=1 # 1=export resolved run config JSON ENABLE_PARTNER_MECHANICS=1 # 1=unlock partner/background commander inputs for headless (web wiring in progress) ENABLE_PARTNER_SUGGESTIONS=1 # 1=enable partner suggestion API and UI chips (dataset auto-refreshes when missing) # PARTNER_SUGGESTIONS_DATASET=config/analytics/partner_synergy.json # Optional override path for the suggestion dataset ############################ # Random Modes (alpha) ############################ RANDOM_MODES=1 # Enable backend random build endpoints RANDOM_UI=1 # Show Surprise/Reroll/Share controls in UI RANDOM_MAX_ATTEMPTS=5 # Cap retry attempts for constrained random builds # RANDOM_TIMEOUT_MS=5000 # Per-attempt timeout (ms) # RANDOM_REROLL_THROTTLE_MS=350 # Minimum ms between reroll requests # RANDOM_STRUCTURED_LOGS=0 # 1=emit structured JSON logs for random builds # RANDOM_TELEMETRY=0 # 1=emit lightweight timing/attempt metrics # HEADLESS_RANDOM_MODE=1 # Force headless runner to invoke random flow instead of scripted build # RANDOM_THEME=Treasure # Legacy single-theme alias (maps to primary theme if others unset) # RANDOM_PRIMARY_THEME=Treasure # Primary theme slug (case-insensitive) # RANDOM_SECONDARY_THEME=Artifacts # Secondary theme slug # RANDOM_TERTIARY_THEME=Tokens # Tertiary theme slug RANDOM_AUTO_FILL=1 # Auto-fill missing secondary/tertiary slots RANDOM_AUTO_FILL_SECONDARY=1 # Explicit secondary auto-fill override (fallback from RANDOM_AUTO_FILL) RANDOM_AUTO_FILL_TERTIARY=1 # Explicit tertiary auto-fill override (fallback from RANDOM_AUTO_FILL) # RANDOM_STRICT_THEME_MATCH=0 # Require strict commander theme matches # RANDOM_CONSTRAINTS= # Inline JSON or path to JSON constraints for random selection # RANDOM_CONSTRAINTS_PATH= # Alternate path-based constraints override (takes precedence if set) # RANDOM_SEED= # Optional deterministic seed (int or string) # RANDOM_OUTPUT_JSON=deck_files/random_build.json # Where to write random build metadata payload # Optional server rate limiting (random endpoints) # RATE_LIMIT_ENABLED=0 # 1=enable server-side rate limiting for random endpoints # RATE_LIMIT_WINDOW_S=10 # window size in seconds # RATE_LIMIT_RANDOM=10 # max random attempts per window # RATE_LIMIT_BUILD=10 # max builds per window # RATE_LIMIT_SUGGEST=30 # max suggestions per window ############################ # Automation & Performance (Web) ############################ WEB_AUTO_SETUP=1 # dockerhub: WEB_AUTO_SETUP="1" WEB_AUTO_REFRESH_DAYS=7 # dockerhub: WEB_AUTO_REFRESH_DAYS="7" WEB_TAG_PARALLEL=1 # dockerhub: WEB_TAG_PARALLEL="1" WEB_TAG_WORKERS=2 # dockerhub: WEB_TAG_WORKERS="4" WEB_AUTO_ENFORCE=0 # dockerhub: WEB_AUTO_ENFORCE="0" # Build Stage Ordering WEB_STAGE_ORDER=new # new|legacy. 'new' (default): creatures → spells → lands → fill. 'legacy': lands → creatures → spells → fill # Ideals UI Mode WEB_IDEALS_UI=slider # input|slider. 'slider' (default): range sliders with live value display. 'input': text input boxes # Tagging Refinement Feature Flags TAG_NORMALIZE_KEYWORDS=1 # dockerhub: TAG_NORMALIZE_KEYWORDS="1" # Normalize keywords & filter specialty mechanics TAG_PROTECTION_GRANTS=1 # dockerhub: TAG_PROTECTION_GRANTS="1" # Protection tag only for cards granting shields TAG_METADATA_SPLIT=1 # dockerhub: TAG_METADATA_SPLIT="1" # Separate metadata tags from themes in CSVs # DFC_COMPAT_SNAPSHOT=0 # 1=write legacy unmerged MDFC snapshots alongside merged catalogs (deprecated compatibility workflow) # WEB_CUSTOM_EXPORT_BASE= # Custom basename for exports (optional). # THEME_CATALOG_YAML_SCAN_INTERVAL_SEC=2.0 # Poll for YAML changes (dev) # WEB_THEME_FILTER_PREWARM=0 # 1=prewarm common filters for faster first renders ############################ # Testing & CI helpers ############################ # EDITORIAL_TEST_USE_FIXTURES=0 # 1=stage lightweight catalog fixtures for editorial governance tests (CI convenience) ############################ # Headless Export Options ############################ # HEADLESS_EXPORT_JSON=1 # 1=export resolved run config JSON alongside CSV/TXT (headless runs only). ############################ # Commander & Theme Selection (Headless / Env Overrides) ############################ # DECK_COMMANDER=Pantlaza, Sun-Favored # Commander name query. # (Index-based theme choices – mutually exclusive with *_TAG names per slot): # DECK_PRIMARY_CHOICE=1 # DECK_SECONDARY_CHOICE=2 # DECK_TERTIARY_CHOICE=3 # (Name-based theme tags – preferred; resolved to indices automatically): # DECK_PRIMARY_TAG=Tokens # DECK_SECONDARY_TAG=Treasure # DECK_TERTIARY_TAG=Sacrifice # DECK_BRACKET_LEVEL=3 # 1–5 Power/Bracket selection. # DECK_ADDITIONAL_THEMES=Lifegain;Tokens Matter # Supplemental themes (comma/semicolon separated list) resolved via theme catalog. # THEME_MATCH_MODE=permissive # permissive|strict fuzzy resolution (strict aborts on unresolved themes). ############################ # Category Toggles (Spell / Creature / Land Inclusion) ############################ # DECK_ADD_LANDS=1 # Include land-building sequence. # DECK_ADD_CREATURES=1 # Add creatures. # DECK_ADD_NON_CREATURE_SPELLS=1 # Bulk add for non-creatures (if supported); else individual toggles below. # DECK_ADD_RAMP=1 # DECK_ADD_REMOVAL=1 # DECK_ADD_WIPES=1 # DECK_ADD_CARD_ADVANTAGE=1 # DECK_ADD_PROTECTION=1 ############################ # Land Count Requests / Adjustments ############################ # DECK_FETCH_COUNT=3 # Requested fetch land count. # DECK_DUAL_COUNT= # Requested dual land count (optional). # DECK_TRIPLE_COUNT= # Requested triple land count (optional). # DECK_UTILITY_COUNT= # Requested utility land count (optional). ############################ # Optional Convenience / Misc (normally container-set or not required) ############################ PYTHONUNBUFFERED=1 # Improves real-time log flushing. TERM=xterm-256color # Terminal color capability. DEBIAN_FRONTEND=noninteractive # Suppress apt UI in Docker builds. ############################ # Editorial / Theme Catalog (Phase D) – Advanced ############################ # The following variables control automated theme catalog generation, # description heuristics, popularity bucketing, backfilling curated YAML, # and optional regression/metrics outputs. They are primarily for maintainers # refining the catalog; leave commented for normal use. # # EDITORIAL_SEED=1234 # Deterministic seed for reproducible ordering & any randomness. # EDITORIAL_AGGRESSIVE_FILL=0 # 1=borrow extra inferred synergies for very sparse themes. # EDITORIAL_POP_BOUNDARIES=50,120,250,600 # Override popularity bucket thresholds (must be 4 ascending ints). # EDITORIAL_POP_EXPORT=0 # 1=write theme_popularity_metrics.json with bucket counts. # EDITORIAL_BACKFILL_YAML=0 # 1=write auto description/popularity back into per-theme YAML (missing only). # EDITORIAL_INCLUDE_FALLBACK_SUMMARY=0 # 1=embed generic description usage summary in theme_list.json. # EDITORIAL_REQUIRE_DESCRIPTION=0 # 1=lint failure if any theme missing description (lint script usage). # EDITORIAL_REQUIRE_POPULARITY=0 # 1=lint failure if any theme missing popularity bucket. # EDITORIAL_MIN_EXAMPLES=0 # (Future) minimum curated examples (cards/commanders) target. # EDITORIAL_MIN_EXAMPLES_ENFORCE=0 # (Future) enforce vs warn. ############################ # Sampling & Rarity Tuning (advanced) ############################ # SPLASH_ADAPTIVE=0 # 1=enable adaptive off-color penalty # SPLASH_ADAPTIVE_SCALE=1:1.0,2:1.0,3:1.0,4:0.6,5:0.35 # RARITY_W_MYTHIC=1.2 # RARITY_W_RARE=0.9 # RARITY_W_UNCOMMON=0.65 # RARITY_W_COMMON=0.4 # RARITY_DIVERSITY_TARGETS=mythic:0-1,rare:0-2,uncommon:0-4,common:0-6 # RARITY_DIVERSITY_OVER_PENALTY=-0.5 ############################ # Theme Preview Cache & Redis (optional) ############################ # THEME_PREVIEW_CACHE_MAX=400 # Max previews cached in memory # WEB_THEME_PREVIEW_LOG=0 # 1=verbose cache logs # THEME_PREVIEW_ADAPTIVE=0 # 1=adaptive cache policy # THEME_PREVIEW_EVICT_COST_THRESHOLDS=5,15,40 # THEME_PREVIEW_BG_REFRESH=0 # 1=background refresh worker # THEME_PREVIEW_BG_REFRESH_INTERVAL=120 # seconds # THEME_PREVIEW_TTL_BASE=300 # THEME_PREVIEW_TTL_MIN=60 # THEME_PREVIEW_TTL_MAX=900 # THEME_PREVIEW_TTL_BANDS=0.2,0.5,0.8 # THEME_PREVIEW_TTL_STEPS=2,4,2,3,1 # THEME_PREVIEW_REDIS_URL=redis://localhost:6379/0 # THEME_PREVIEW_REDIS_DISABLE=0 # 1=disable redis even if URL set ###################################################################### # Notes # - CLI arguments override env vars; env overrides JSON config; JSON overrides defaults. # - For include/exclude card functionality enable ALLOW_MUST_HAVES=1 (Web) and use UI or CLI flags. # - For Random Modes UI, set RANDOM_MODES=1 and RANDOM_UI=1; see /random. # - Path overrides must point to mounted volumes inside the container. # - Remove a value or leave it commented to fall back to internal defaults. ######################################################################