Running the Game

Prerequisites

Docker Desktop (or Docker Engine + Compose v2)
Git
4 GB free disk, 2 GB RAM

Quick Start with Docker

# 1. Clone the repo
git clone https://github.com/your-org/conquerv5.git
cd conquerv5/new

# 2. Start everything
docker compose up -d

# 3. Run database migrations
docker compose exec backend alembic upgrade head

# 4. Open the game
#    Frontend:  http://localhost:5174
#    API docs:  http://localhost:8001/docs

The first docker compose up builds images and may take a few minutes. Subsequent starts are fast.

Services

Service	URL / Port	Description
`frontend`	localhost:5174	React game UI (nginx)
`backend`	localhost:8001	FastAPI REST API
`db`	localhost:5432	PostgreSQL 16
`redis`	localhost:6379	Redis (Celery broker)
`worker`	—	Celery turn processor
`beat`	—	Celery scheduler (every 6 hrs)

Local Development (no Docker)

Backend

cd new/backend
pip install -e ".[dev]" aiosqlite

# Run tests (uses SQLite in-memory, no database needed)
python3 -m pytest

# Start dev server (requires PostgreSQL)
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/conquer \
  uvicorn app.main:app --reload

Frontend

cd new/frontend
npm install

# Set backend URL
echo "VITE_API_URL=http://localhost:8001" > .env

# Start dev server
npm run dev
# Open http://localhost:5173

Environment Variables

Variable	Default	Description
`DATABASE_URL`	postgresql+asyncpg://conquer:conquer@db:5432/conquer	PostgreSQL connection
`REDIS_URL`	redis://redis:6379/0	Redis/Celery broker
`SECRET_KEY`	change-me-in-production	JWT signing key — change this!
`DEBUG`	false	Enables SQL echo and stack traces
`VITE_API_URL`	http://localhost:8001	Frontend → backend URL

Production: Change SECRET_KEY to a random 32+ character string. Do not run with DEBUG=true in production.

Database Migrations

# Apply all migrations
docker compose exec backend alembic upgrade head

# Create a new migration after model changes
docker compose exec backend alembic revision --autogenerate -m "description"

Turn Scheduling

By default the Celery beat scheduler processes all active worlds every 6 hours. Admins can also trigger turns manually from the Admin Panel.

To change the schedule, edit app/tasks/celery_app.py:

beat_schedule={
    "process-all-turns": {
        "task": "app.tasks.turn_tasks.process_all_worlds",
        "schedule": crontab(minute=0, hour="*/6"),  # change interval here
    },
},

Stopping the Server

docker compose down          # stop containers, keep data
docker compose down -v       # stop and delete all data (reset)