From 0eacaba28b78a217faff23f57671a015a19b3b2a Mon Sep 17 00:00:00 2001
From: admin <admin@optimex.systems>
Date: Mon, 20 Jul 2026 22:56:14 +0000
Subject: [PATCH] docs: update README with volume mount instructions and Docker
 setup

---
 README.md | 171 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 144 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index fca42d1..76356e3 100644
--- a/README.md
+++ b/README.md
@@ -24,9 +24,11 @@ A modern web-based implementation of the MTG Online multiplayer Magic: The Gathe
 
 ### Prerequisites
 
-- Python 3.12+
-- PostgreSQL 14+
+- Docker and Docker Compose
+- Python 3.12+ (for development)
+- PostgreSQL 14+ (if running without Docker)
 - Redis (optional, for caching)
+- **MTGJSON data files** (see below)
 
 ### Installation
 
@@ -37,46 +39,51 @@ git clone https://github.com/yourusername/mtgonline-web.git
 cd mtgonline-web
 ```
 
-2. **Create a virtual environment**
-
-```bash
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-```
-
-3. **Install dependencies**
-
-```bash
-cd backend
-pip install -r requirements.txt
-```
-
-4. **Configure environment**
+2. **Configure environment**
 
 ```bash
 cp .env.example .env
 # Edit .env with your configuration
 ```
 
-5. **Set up the database**
+3. **Prepare MTGJSON data files**
+
+The application requires MTGJSON data files. You have two options:
+
+**Option A: Download from MTGJSON (recommended)**
 
 ```bash
-# Create PostgreSQL database
-createdb mtgonline
+# Create data directory
+mkdir -p data
 
-# Run migrations (when Alembic is set up)
-alembic upgrade head
+# Download required files from MTGJSON
+# See scripts/download-mtgjson.sh for automated download
+bash scripts/download-mtgjson.sh
 ```
 
-6. **Run the application**
+**Option B: Provide your own JSON files**
+
+Place these files in the `data/` directory:
+- `AllSetFiles/` (directory containing set JSON files)
+- `AllPrintings.json`
+- `AllIdentifiers.json`
+- `CardTypes.json`
+- `DeckList.json`
+- `Keywords.json`
+- `SetList.json`
+
+### Running with Docker (recommended)
 
 ```bash
-uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+# Copy the data directory to a volume mount path
+mkdir -p ~/mtg-data
+cp -r data/* ~/mtg-data/
+
+# Start the application
+sudo docker compose up -d
 ```
 
-7. **Access the API documentation**
-
-Open http://localhost:8000/docs to view the FastAPI Swagger UI.
+The backend container will automatically process the JSON files from the mounted volume and populate the database.
 
 ## Project Structure
 
@@ -117,6 +124,116 @@ mtgonline-web/
 └── README.md
 ```
 
+
+## Docker Deployment
+
+### 1. Prepare the Data Directory
+
+Create a directory on your host machine to store the MTGJSON files:
+
+```bash
+mkdir -p ~/mtg-data
+cp -r data/* ~/mtg-data/
+```
+
+### 2. Configure Environment
+
+```bash
+cp .env.example .env
+# Edit .env with your configuration
+```
+
+### 3. Mount and Start
+
+```bash
+# Start with data directory mounted (Linux/macOS)
+sudo docker compose up -d
+
+# The data directory is automatically mounted to /app/data in the backend container
+# Alternatively, specify a custom path:
+sudo docker compose up -d --build
+```
+
+The backend will:
+- Detect the JSON files in the mounted volume
+- Upsert all data into the PostgreSQL database
+- Start the FastAPI application
+
+### 4. Verify
+
+```bash
+# Check backend logs
+docker compose logs -f backend
+
+# Test health endpoint
+curl http://localhost:8000/health
+```
+
+### Updating Data
+
+When MTGJSON releases updates:
+1. Copy new `.json` files to `~/mtg-data/`
+2. The backend will automatically process new files on next startup
+3. Or trigger a manual refresh via `/refresh` endpoint
+
+## Development
+
+### Run Locally
+
+```bash
+cd backend
+pip install -r requirements.txt
+python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Run Tests
+
+```bash
+cd backend
+pytest
+```
+
+## Project Structure
+
+```
+mtgonline-web/
+├── backend/
+│   ├── app/
+│   │   ├── core/           # Core configuration and utilities
+│   │   │   ├── settings.py # Application settings
+│   │   │   ├── database.py # Database engine and sessions
+│   │   │   └── security.py # Authentication and password hashing
+│   │   ├── models/         # SQLAlchemy ORM models
+│   │   │   └── models.py
+│   │   ├── schemas/        # Pydantic schemas
+│   │   │   ├── schemas.py
+│   │   │   ├── proto_messages.py
+│   │   │   └── protocol_constants.py
+│   │   ├── routers/        # API route handlers
+│   │   │   ├── auth.py
+│   │   │   ├── users.py
+│   │   │   ├── decks.py
+│   │   │   ├── rooms.py
+│   │   │   ├── games.py
+│   │   │   ├── admin.py
+│   │   │   └── ws.py
+│   │   ├── services/       # Business logic services
+│   │   │   ├── game_server.py
+│   │   │   ├── card_database.py
+│   │   │   └── deck_parser.py
+│   │   └── main.py         # FastAPI application
+│   ├── tests/              # Test suite
+│   ├── requirements.txt    # Python dependencies
+│   ├── pyproject.toml      # Ruff configuration
+│   └── .env.example        # Environment template
+├── frontend/               # React/TypeScript frontend (coming soon)
+├── shared/                 # Shared protocol definitions
+│   └── proto/              # Protocol buffer definitions
+├── data/                   # MTGJSON data files (not in git)
+├── scripts/                # Utility scripts
+└── README.md
+```
+
 ## API Endpoints
 
 ### Authentication