205 lines
6.3 KiB
Markdown
205 lines
6.3 KiB
Markdown
# Rail Game
|
|
|
|
A browser-based railway simulation game using real-world railway maps from OpenStreetMap.
|
|
|
|
## At a glance
|
|
|
|
- Frontend: React + Vite (TypeScript)
|
|
- Backend: Python (FastAPI, SQLAlchemy)
|
|
- Database: PostgreSQL with PostGIS (spatial types)
|
|
- Mapping: Leaflet + OpenStreetMap
|
|
|
|
## Features
|
|
|
|
- Real-world railway maps
|
|
- Interactive Leaflet map preview of a demo network snapshot
|
|
- Build and manage your railway network
|
|
- Dynamic train schedules and simulated trains
|
|
|
|
## Current project layout
|
|
|
|
This repository contains a full-stack demo app (frontend + backend), supporting scripts, docs and infra. Key folders:
|
|
|
|
- `backend/` — FastAPI application, models, services, migration scripts and backend tests.
|
|
- `frontend/` — React app (Vite) and frontend tests.
|
|
- `docs/` — Architecture docs and ADRs.
|
|
- `infra/` — Deployment assets (Dockerfiles, compose files, init scripts).
|
|
- `data/` — Fixtures and imported OSM snapshots.
|
|
- `scripts/` — Utility scripts (precommit helpers, setup hooks).
|
|
- `tests/` — End-to-end tests and cross-cutting tests.
|
|
|
|
Refer to the in-repo `docs/` for architecture decisions and deeper design notes.
|
|
|
|
## Installation
|
|
|
|
Below are concise, verified steps for getting the project running locally. Commands show both PowerShell (Windows) and Bash/macOS/Linux variants where they differ.
|
|
|
|
## Prerequisites
|
|
|
|
- Git
|
|
- Python 3.10+ (3.11 recommended) and pip
|
|
- Node.js 16+ (or the version required by `frontend/package.json`)
|
|
- PostgreSQL with PostGIS if you want to run the full DB-backed stack locally
|
|
- Docker & Docker Compose (optional, for containerized dev)
|
|
|
|
### Clone repository
|
|
|
|
PowerShell / Bash
|
|
|
|
git clone https://github.com/zwitschi/rail-game.git
|
|
cd rail-game
|
|
|
|
### Backend: create virtual environment and install
|
|
|
|
PowerShell
|
|
|
|
python -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
python -m pip install -e .[dev]
|
|
|
|
Bash / macOS / Linux
|
|
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
python -m pip install -e '.[dev]'
|
|
|
|
### Notes
|
|
|
|
- Installing editable extras (`.[dev]`) installs dev/test tools used by the backend (pytest, black, isort, alembic, etc.).
|
|
|
|
### Environment file
|
|
|
|
Copy the sample `.env.example` to `.env` and adjust the database connection strings as needed.
|
|
|
|
PowerShell
|
|
|
|
Copy-Item .env.example .env
|
|
|
|
Bash
|
|
|
|
cp .env.example .env
|
|
|
|
### Important environment variables
|
|
|
|
- `DATABASE_URL` — runtime DB connection for the app
|
|
- `TEST_DATABASE_URL` — database used by pytest in CI/local tests
|
|
- `ALEMBIC_DATABASE_URL` — used when running alembic outside the app process
|
|
|
|
### Database (Postgres + PostGIS)
|
|
|
|
If you run Postgres locally, create the dev/test DBs and ensure the `postgis` extension is available. Example (psql):
|
|
|
|
-- create DBs (run in psql as a superuser or role with create privileges)
|
|
CREATE DATABASE railgame_dev;
|
|
CREATE DATABASE railgame_test;
|
|
|
|
-- connect to the db and enable extensions
|
|
\c railgame_dev
|
|
CREATE EXTENSION IF NOT EXISTS postgis;
|
|
CREATE EXTENSION IF NOT EXISTS pgcrypto;
|
|
|
|
Adjust DB names and roles to match your `.env` values.
|
|
|
|
### Quick database setup (recommended)
|
|
|
|
For a streamlined setup, use the included initialization script after configuring your `.env` file:
|
|
|
|
PowerShell / Bash
|
|
|
|
python scripts/init_demo_db.py
|
|
|
|
This script validates your environment, runs migrations, and loads demo OSM data. Use `--dry-run` to preview changes, or `--region` to load specific regions.
|
|
|
|
**Note**: The script uses `python-dotenv` to load your `.env` file. If not installed, run `pip install python-dotenv`.
|
|
|
|
### Run migrations
|
|
|
|
PowerShell / Bash
|
|
|
|
cd backend
|
|
alembic upgrade head
|
|
cd ..
|
|
|
|
If you prefer to run alembic with a specific URL without editing `.env`, set `ALEMBIC_DATABASE_URL` in the environment before running the command.
|
|
|
|
### Load OSM fixtures (optional)
|
|
|
|
Use the included scripts to refresh stations and tracks from saved OSM fixtures. This step assumes the database is migrated and reachable.
|
|
|
|
PowerShell / Bash
|
|
|
|
# dry-run
|
|
python -m backend.scripts.osm_refresh --region all --no-commit
|
|
|
|
# commit to DB
|
|
python -m backend.scripts.osm_refresh --region all
|
|
|
|
See `backend/scripts/*.py` for more granular import options (`--skip-*` flags).
|
|
|
|
### Frontend
|
|
|
|
Install dependencies and run the dev server from the `frontend/` directory.
|
|
|
|
PowerShell / Bash
|
|
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
|
|
The frontend runs at `http://localhost:5173` by default (Vite). The React app talks to the backend API at the address configured in its environment (see `frontend` README or `vite` config).
|
|
|
|
### Run backend locally (development)
|
|
|
|
PowerShell / Bash
|
|
|
|
# from project root
|
|
uvicorn backend.app.main:app --reload --port 8000
|
|
|
|
The backend API listens at `http://localhost:8000` by default.
|
|
|
|
### Tests & linters
|
|
|
|
Backend
|
|
|
|
pytest
|
|
black backend/ && isort backend/
|
|
|
|
Frontend
|
|
|
|
cd frontend
|
|
npm run lint
|
|
npm run build # type/build check
|
|
|
|
### Docker / Compose (optional)
|
|
|
|
Build and run both services with Docker Compose if you prefer containers:
|
|
|
|
PowerShell / Bash
|
|
|
|
docker compose up --build
|
|
|
|
This expects a working Docker environment and may require you to set DB URLs to point to the containerized Postgres service if one is defined in `docker-compose.yml`.
|
|
|
|
## Troubleshooting
|
|
|
|
- If migrations fail with missing PostGIS functions, ensure `postgis` is installed and enabled in the target database.
|
|
- If alembic autogenerate creates unexpected changes, confirm the models being imported match the app import path used by `alembic` (see `backend/migrations/env.py`).
|
|
- For authentication/debugging, the demo user is `demo` / `railgame123` (used by some integration tests and the demo auth flow).
|
|
- If frontend dev server fails due to node version, check `frontend/package.json` engines or use `nvm`/`nvm-windows` to match the recommended Node version.
|
|
|
|
## API preview
|
|
|
|
Some useful endpoints for local testing:
|
|
|
|
- `GET /api/health` — readiness probe
|
|
- `POST /api/auth/register` — demo account creation + JWT
|
|
- `POST /api/auth/login` — exchange credentials for JWT (demo user: `demo` / `railgame123`)
|
|
- `GET /api/auth/me` — current user profile (requires bearer token)
|
|
- `GET /api/network` — sample network snapshot (requires bearer token)
|
|
|
|
## Contributing
|
|
|
|
- See `docs/` for architecture and ADRs.
|
|
- Keep tests green and follow formatting rules (black, isort for Python; Prettier/ESLint for frontend).
|
|
- Open issues or PRs for bugs, features, or docs improvements.
|