almena-registry-api

The backend of the Almena Network registry portal: a FastAPI service on PostgreSQL, consumed by registry-web.

Built with Python 3.13, uv, SQLAlchemy 2 (async, asyncpg), Alembic for migrations and pydantic-settings for configuration.

Quick start

Needs uv, Task and Docker.

task init   # .env from .env.example, with a random database password
task up     # PostgreSQL + migrations + API in Docker
task health # {"status":"ok","version":"0.1.0","database":"ok"}

The API answers at http://localhost:8000. For development, task dev runs it locally with auto-reload against PostgreSQL in Docker, and serves the interactive Scalar reference at http://localhost:8000/docs.

Configuration

All settings are REGISTRY_* environment variables, read from the environment or .env; .env.example lists and explains every one.

Variable	Default
REGISTRY_ENVIRONMENT	development	production hides /docs and /openapi.json (the Docker image's default)
REGISTRY_CORS_ORIGINS	["http://localhost:3000"]	Origins allowed by CORS, as a JSON list
REGISTRY_DB_HOST / REGISTRY_DB_PORT	localhost / 5432	PostgreSQL server
REGISTRY_DB_NAME / REGISTRY_DB_USER / REGISTRY_DB_PASSWORD	registry / registry / —	Database and credentials; Compose creates them on the first start
REGISTRY_LOG_LEVEL	INFO	DEBUG, INFO, WARNING or ERROR

Endpoints

GET /health	Liveness: the process is up
GET /health/ready	Readiness: 503 while the database is unreachable
/api/v1/…	The registry API
GET /docs, GET /openapi.json	API reference (Scalar) and the OpenAPI document, generated from the code (not in production)

Database migrations

The schema is managed with Alembic; task up applies pending migrations (the migrate service) before starting the API.

task db:revision -- "add entries"   # autogenerate a migration from the models
task db:migrate                     # apply it
task db:shell                       # psql on the Docker database

Review every autogenerated migration before committing it.

Development

task --list shows every task. Before sending a change, task check (formatting, ruff, mypy, tests) must pass; see CONTRIBUTING.md and AGENTS.md for the code layout.

Contributing and security

See CONTRIBUTING.md and the Code of Conduct. Report vulnerabilities privately as described in SECURITY.md.

License

Licensed under the Apache License 2.0.