Universal Gaming Accounts Backend

Optional self-hosted account and leaderboard service for Universal Gaming.

The Flutter app is fully playable without this service. The backend adds:

• Username/password accounts with optional e-mail.
• Stable UUID identities and optional renaming.
• E-mail confirmation and password reset.
• A competitive leaderboard for ten solo games.
• Server-validated online chess.
• A read-only management panel.
• A release proxy for the app's update checker and web footer.

Current version

Item	Value
Backend version	1.4.0
Node.js	20+
Primary database	PostgreSQL 16
Development fallback	SQLite
Default port	6767
Public instance	https://account.games.emilyh.de
App repository	Emily/UniversalGamingApp
App wiki	Universal Gaming wiki

Start here

• Deployment — Docker Compose, reverse proxy, upgrades and backups.
• Configuration — every environment variable and recommended production values.
• API Reference — accounts, leaderboard, chess, releases and management.
• Database and Migrations — schema, migration policy and SQLite fallback.
• Security — password hashing, JWTs, rate limits, CORS, proxies and logging.
• Operations — logs, health checks, SMTP, backups, restore and monitoring.
• Development and Testing — local setup, test suite and release process.
• Troubleshooting — common deployment, database, SMTP and API errors.

Design principles

• Optional. The game never requires an account.
• Small surface area. Accounts, scores, chess and a release proxy only.
• PostgreSQL first. Compose uses PostgreSQL; SQLite remains for tests and local development.
• Server-authoritative chess. Moves are replayed with chess.js; the client is never trusted.
• No plaintext secrets. Passwords are hashed; e-mail and reset tokens are stored as SHA-256 hashes.
• Safe upgrades. update.sh takes a pg_dump backup and runs ordered migrations before restarting.
• Operable. Health checks, structured request logs, a management panel and documented backups.

Quick start

git clone https://git.emilyh.de/Emily/UniversalGamingApp-Backend.git
cd UniversalGamingApp-Backend

cp .env.example .env
# Set JWT_SECRET, POSTGRES_PASSWORD and CORS_ORIGINS.

docker compose up -d --build
curl http://localhost:6767/healthz

See Deployment for production guidance.

Repository map

Path	Purpose
src/app.js	Express application and routes
src/config.js	Environment parsing, defaults and validation
src/db.js	PostgreSQL/SQLite data access
src/migrations.js	Ordered PostgreSQL migrations
src/migrate.js	Standalone migration runner
src/auth.js	JWT issuing and verification
src/passwords.js	bcrypt + SHA-256 password hashing
src/mailer.js	SMTP transport and e-mail templates
src/chess.js	Server-side chess validation
src/leaderboard.js	Leaderboard validation and ranking helpers
src/management.js	Read-only management panel
src/http_error.js	Typed HTTP errors
test/	Node test suite
docker-compose.yml	PostgreSQL + accounts services
update.sh	Backup, pull, migrate and restart