NeroSpatial Backend

FastAPI backend for the NeroSpatial platform.

Setup

Prerequisites

• Python 3.11+
• uv package manager

Installation

1. Install dependencies using uv:

uv sync

2. Create a .env file from the example:

cp .env.example .env

3. Run the application:

uv run uvicorn main:app --reload

Or using Python directly:

uv run python main.py

Endpoints

Health Endpoints

• GET /health - Detailed health check with dependency status
• GET /ready - Readiness probe (Kubernetes/load balancer)
• GET /live - Liveness probe (Kubernetes)

Application Endpoints

• GET /helloworld - Hello world endpoint

Infrastructure Setup

Local Development

Start infrastructure services (PostgreSQL, Redis, Jaeger) using Docker Compose:

docker compose -f docker-compose.infra.yml up -d

This will start:

• PostgreSQL on port 5432
• Redis on port 6379
• Jaeger (tracing) on ports 4317 (OTLP) and 16686 (UI)

Database Initialization

The database schema is automatically initialized when the PostgreSQL container starts for the first time via scripts/init-db.sql.

JWT Key Generation

Generate JWT RS256 keys for authentication:

./scripts/generate-keys.sh

This creates keys/private.pem and keys/public.pem. Store these in Azure Key Vault for production.

Azure Key Vault Setup

Set up Azure Key Vault and upload secrets:

./scripts/setup-keyvault.sh

This script will:

1. Create Key Vault (if not exists)
2. Create Service Principal with proper permissions
3. Upload JWT keys and other secrets
4. Output credentials for your .env file

Configuration

Configuration is managed through a hierarchy:

1. Azure App Configuration (single source of truth for production/staging)

   • Non-secret settings (URLs, ports, feature flags)
   • Environment-specific configuration using labels

2. Azure Key Vault (secrets)

   • Passwords, JWT keys, OAuth credentials
   • Referenced from App Configuration

3. .env file (bootstrap and development fallback)

   • Azure credentials to access App Config and Key Vault
   • Local overrides for development
   • Minimal - only what's needed to bootstrap

Environment Validation

• Production/Staging: Requires Azure App Config and Key Vault URLs. Server will not start without them.
• Development: Optional Azure services. Falls back to .env file if not configured.

See .env.example for all available configuration options.

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality before commits.

Setup

After cloning the repository, install the hooks:

uv sync --extra dev
uv run pre-commit install

Usage

Hooks run automatically on git commit. To run manually:

# Run on all files
uv run pre-commit run --all-files

# Run on staged files only
uv run pre-commit run

Hooks Configured

• Ruff Linter: Checks for Python linting errors and auto-fixes them
• Ruff Formatter: Formats Python code according to project style
• Trailing Whitespace: Removes trailing whitespace
• End of File Fixer: Ensures files end with newline
• YAML/JSON/TOML Checkers: Validates configuration files
• Large File Check: Prevents committing large files (>1MB)
• Merge Conflict Check: Detects merge conflict markers
• Debugger Check: Prevents committing debugger imports

CI/CD Pipeline

For detailed CI/CD documentation, see docs/CI_CD.md.

Future Integration

The application is designed to integrate with:

• Azure Key Vault (for secrets)
• Azure App Configuration Store (for configurations)