Userverse is an open-source FastAPI backend for users, companies, authentication, global and company-scoped roles, permissions, and company memberships. PostgreSQL and MySQL are supported deployment databases; SQLite is reserved for isolated development and tests.
Requirements: Git, Docker with Compose v2, uv, and OpenSSL.
git clone https://github.com/SoftwareVerse/userverse.git
cd userverse
./scripts/setup_dev.sh postgres
make devUse MySQL instead:
./scripts/setup_dev.sh mysql
make devThe setup script creates .env only when it is missing, generates a local JWT secret, installs locked development and documentation dependencies, starts the selected database, validates configuration, applies migrations, and installs pre-commit hooks. It never overwrites an existing .env.
Open http://127.0.0.1:8500/ for health and http://127.0.0.1:8500/docs for OpenAPI documentation.
See Developer setup for prerequisites, manual setup, database profiles, and daily commands.
make help # list every supported command
make dev # start the API with reload
make config-check # validate .env without showing secrets
make migrate # apply migrations
make migration MIGRATION="name" # create and review a migration
make test # run tests quickly
make coverage # run the required 100% coverage gate
make lint # Black, Ruff, YAML, and diff checks
make check # lint and coverage
make docs # serve documentation locally
make docker-build # build the production image
make docker-test # full image, Trivy, DB, and health testCopy the sample manually when not using the setup script:
cp .env.example .env
openssl rand -hex 32Set the generated value as JWT__SECRET, select a PostgreSQL or MySQL DATABASE_URL, then run:
make config-check
make migrateProcess environment variables override .env. See Configuration for every supported field and production validation rule.
The repository contains 407 tests and enforces 100% statement coverage for measured application modules:
make checkPre-commit runs Black, Ruff, YAML validation, secret detection, and Hadolint. Install it manually with uv run pre-commit install if setup was not run. See Testing.
Never rely on automatic table creation in production. Apply the migration chain deliberately:
make migrate
uv run alembic currentFor multiple application replicas, run exactly one migration job and start API replicas with RUN_MIGRATIONS=false. See Migration guide and Production deployment.
The verified public image is published to:
docker pull ghcr.io/softwareverse/userverse:latestUse immutable release or commit tags in production. Docker CI builds the real Dockerfile, scans it with Trivy, migrates PostgreSQL and MySQL, starts the API, and verifies / plus Docker health before publishing.