docs: update README with volume mount instructions and Docker setup
This commit is contained in:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user