A FastAPI backend for secure authentication and user management. It includes role-based access control, user CRUD endpoints, token refresh, Docker-based local services, Alembic migration scaffolding, and a small developer workflow for linting, testing, and CI.
- Authentication and authorization with Basic login, Bearer access tokens, and refresh tokens.
- Role-based access control for user, moderator, and admin actions.
- User CRUD endpoints,
/me, username search, pagination, and creation-year filtering. - OpenAPI documentation at
/docsand ReDoc at/redoc. - Docker Compose services for the API, PostgreSQL, and Nginx.
- Separate local PostgreSQL test service in
docker-compose.test.yml. - Alembic scaffolding for async SQLAlchemy migrations.
- GitHub Actions CI for Ruff, Black formatting through pre-commit, and pytest coverage against PostgreSQL.
- Docker or Docker Compose for local database services.
- Poetry for Python dependency management.
- Python 3.12 is used by the Docker image and CI.
Copy the example environment file and adjust values as needed:
cp .env.example .envInstall dependencies:
make installStart the application stack:
docker-compose up -d --buildInitialize the database and create the initial admin user:
docker-compose exec api python -m cli db initThe API is available at http://localhost:8000. Nginx proxies it at
http://localhost.
The ASGI application target is core.server:app. main.py is kept as a
direct-run convenience wrapper and does not start Uvicorn on import.
The Makefile provides the common local workflow:
make install # poetry install
make format # ruff autofix and Black through pre-commit
make lint # ruff check
make test # pytest
make coverage # coverage run -m pytest, then coverage report
make pre-commit # pre-commit run --all-files
make ci # local CI subset: lint and coveragePass focused pytest arguments with PYTEST_ARGS:
make test PYTEST_ARGS='tests/api/v1/test_tokens.py'make typecheck runs mypy ., but it is not part of the default CI target yet
because the current strict mypy baseline is not clean.
Tests expect a PostgreSQL database whose name is the configured POSTGRES_DB
with -test appended. The test Compose file creates that database with local
defaults:
make db-test-up
make test
make db-test-downBy default this uses:
POSTGRES_USER=postgresPOSTGRES_PASSWORD=postgresPOSTGRES_HOST=localhostPOSTGRES_PORT=5432POSTGRES_DB=secure_waypoint
Override those variables in the shell or when invoking make if needed.
Alembic is configured in alembic.ini and alembic/env.py. The migration
environment imports app.models.Base.metadata and reads the async PostgreSQL
URL from core.config.config.SQLALCHEMY_DATABASE_URI.
Create a migration:
poetry run alembic revision --autogenerate -m "describe change"Apply migrations:
poetry run alembic upgrade headLogin uses Basic authentication:
curl -X POST http://localhost:8000/api/v1/tokens \
-H 'Authorization: Basic <base64 username:password>'Refresh tokens are submitted in the request body while the current access token is passed as the Bearer token:
curl -X PUT http://localhost:8000/api/v1/tokens \
-H 'Authorization: Bearer <access-token>' \
-H 'Content-Type: application/json' \
-d '{"refresh_token":"<refresh-token>"}'Refresh tokens are type-checked and bound to the same user as the access token.
GitHub Actions is configured at .github/workflows/ci.yml. It runs on pushes
and pull requests, starts a PostgreSQL service, installs Poetry dependencies,
then runs:
poetry run ruff check .poetry run pre-commit run black --all-filespoetry run coverage run -m pytestpoetry run coverage report