Getting started

Production URL: https://asi-database-node-api.arybit.co.ke

Use Python 3.12+ and Bash. Install dependencies in a virtual environment:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r backend/requirements.lock -r backend/requirements-dev.txt
python tools/verify.py
python -m pytest backend/tests -q -p no:cacheprovider

Run local diagnostics:

cd backend
python -m uvicorn app:app --host 127.0.0.1 --port 8080

Local /docs provides Swagger UI; /openapi.json supplies the contract. These endpoints are disabled in staging and production. /health works without a configured database; /ready returns 503 until credentials and the local database work. Database installation is separate from starting FastAPI.

The live console requires HTTPS. Public diagnostics work without authentication; database queries and lifecycle operations use the VM operator token through the separate loopback operator service. See console operations. See API reference and database connections.

Application contract tests and opt-in setup

Use disposable MySQL 8.0 and MariaDB 10.11 databases, each named asi_test with the explicit test account used in backend/tests/test_application.py. The CI workflow mysql-integration.yml starts them independently. Local tests accept their loopback ports, for example:

TEST_MYSQL_PORTS=13306,13307 python -m pytest backend/tests/test_application.py -q
python tools/export-openapi.py --check

Never point these tests at a shared or production instance. They create schema, service identities and fixtures and deliberately modify migration ledger state. TEST_MYSQL_ROOT_PASSWORD optionally enables creation of a restricted disposable runtime role. TEST_MYSQL_RUNTIME=1 selects a pre-provisioned restricted test role; without either flag tests use the disposable schema-owner account and privilege checks are skipped. No SQLite result is treated as engine qualification.

For a local API, install Database/mysql-auth explicitly with test migration credentials, register a service identity using backend/service-identity.py, and set APPLICATION_API_ENABLED=1, DB_ENGINE=mysql and DB connection settings before starting Uvicorn. See qualification and service identity management. HTTP loopback is for local tests only; PHP integration must use certificate-verified HTTPS. No production credentials belong in commands, browser assets or Git.