Skip to content

About

No description or website provided.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

3,112 Commits

Folders and files

Repository files navigation

LleidaHack Backend

FastAPI API for LleidaHack and HackEPS: registration, teams, physical badge assignment, check-in, meals, LleidaCoins, Live event operations and company judging. HackEPS, Gestió and Live are separate frontend repositories.

Start locally

Requirements: Python 3.12+, uv, and Docker running. Install the locked dependencies from the repository root:

uv sync --frozen

Choose one environment; both launch the API on port 8000 and cannot run together.

Environment Command Purpose
Event operations bash scripts/local-operations.sh PostgreSQL on 55439, Redis on 56379, seeded event and role accounts; no mail delivery service
Registration and mail uv run python install/local.py Isolated database on 55440 and capture-only mail on 8001; see local launcher

The event launcher stores its settings in ignored .env.operations.local and uses database llh_operations_dev. It applies migrations and runs the demo seeds; use it to initialize a demo, not to reset an ongoing rehearsal. To restart only the API with existing rehearsal data:

uv run --env-file .env.operations.local uvicorn main:app --host 127.0.0.1 --port 8000

Frontend processes start separately: HackEPS on 3001 (/organitzacio for scanning), Live on 3000 and Gestió on 5175. Point them at this API. Keep real credentials and external delivery workers out of a local rehearsal.

Configure an existing environment

See configuration for secrets, mail, Redis and browser origins. For a manually configured database and services:

cp .env.example .env
# Edit .env before running the following commands.
export PYTHONPATH=backend:.
uv run --env-file .env alembic upgrade head
uv run --env-file .env uvicorn main:app --host 127.0.0.1 --port 8000 --reload

The generated mail client is versioned under backend/generated_src. When using an existing environment, set PYTHONPATH=backend:. so imports resolve; the local launchers and Docker image configure their import paths themselves.

Verify and develop

  • Swagger, ReDoc, OpenAPI.
  • GET /health/live: process liveness.
  • GET /health/ready: database and Redis readiness; returns 503 when unavailable.
  • Sign in using HTTP Basic at GET /v1/auth/login, then use the returned access token as a Bearer token. Company accounts use the separate company portal API.
uv run --frozen ruff check .
uv run --frozen ruff format --check .
# Requires disposable PostgreSQL and Redis; read tests/README.md first.
uv run --frozen pytest -q

Tests reset the configured test database schema. Never use the rehearsal or production database for the test suite.

Create migrations with uv run --env-file .env alembic revision --autogenerate -m "describe_change", review the generated SQL and rehearse preservation before a production migration. Retain the complete Alembic history.

Deployment

The supported production path is Docker Compose with immutable release images, backups and explicit activation. Follow the deployment runbook. GitHub Actions validates releases; merging a PR does not activate the backend. The manual preparation workflow builds a candidate, not a production cutover.

The Dockerfile's default command applies migrations before starting Gunicorn. Production Compose overrides that command to keep migrations a separate release step. Do not substitute a bare docker run for the production runbook.

Repository map

Path Responsibility
main.py, App.py Application entry point and initialization
src/impl/ Domain models, schemas, services and routes
src/configuration/Settings.py Environment settings and validation
src/utils/ Shared authentication, request protection and infrastructure helpers
backend/generated_src/ Required generated mail client; regenerate rather than hand-edit
alembic/ Versioned database migrations
scripts/ Local fixtures, administration and badge printing tools
install/ Isolated local API and captured mail launcher
deploy/ Release, backup/restore, monitoring and worker tooling
tests/ Regression suite against disposable services
docs/ Documentation index

See the documentation index for event operations, integrations, security and historical release notes.

About

No description or website provided.

Topics

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages