Development and Deployment

Development workflow

Flasgo requires Python 3.14 or newer and uses modern Python tooling.

Tool	Purpose
uv	Environment and dependency management
ruff	Linting and formatting
ty	Type checking
pytest	Test execution
uvicorn	ASGI server for development and production

Useful commands:

uv venv
uv lock --check
uv sync --frozen --group dev
uv pip check
uv run --frozen ruff check .
uv run --frozen ruff format --check .
uv run --frozen ty check
uv run --frozen pytest
uv audit --frozen
uv build
git diff --check

Run the built-in development flow:

uv run flasgo run app.py --reload

The flasgo run command accepts Python files, extensionless local files, package directories, module paths, or target:attribute strings with nested attributes. File and package targets establish their import root automatically; the default app lookup checks app and then application. Useful flags include --app, --host, --port, --reload, --no-reload, and repeatable additive --reload-dir values. The reloader stops its server child on Ctrl+C or SIGTERM; see CLI and Migrations.

You can also run the app directly with uvicorn:

uv run uvicorn app:app --reload --host 127.0.0.1 --port 8000

Inspect the application without serving traffic:

uv run flasgo routes app.py
uv run flasgo openapi app.py --output openapi.json
uv run flasgo check app.py

Flasgo 0.9.0 adds policy deployment checks and baseline comparisons. Adopt flasgo check app.py --deploy and flasgo check app.py --against policy.json after declaring route access and reviewing the baseline.

Production deployment

Flasgo is intended to run behind a production ASGI server and a reverse proxy or edge platform.

Typical production command:

# Load a stable FLASGO_SECRET_KEY from your deployment secret store.
uv run uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4 --no-proxy-headers

Do not trust proxy headers by default. If a reverse proxy supplies forwarded identity, make the app server unreachable directly and configure trust only for a proxy that overwrites client-supplied values.

Production checklist:

• Disable debug mode
• Load secrets from environment variables
• Set explicit allowed hosts
• Enable secure cookies
• Leave built-in docs disabled unless access is controlled with DOCS_AUTH_BACKEND
• Keep WebSocket origin checks enabled and allowlist exact cross-origin frontends
• Protect the optional metrics endpoint with a long bearer token and network policy
• Configure OpenTelemetry export, exclusions, and sampling deliberately when tracing is enabled
• Use an edge or shared store for global rate limits across workers
• Send critical background work to a durable queue
• Run multiple workers where appropriate
• Terminate TLS at a trusted reverse proxy or platform edge

The default route limiter, metrics registry, and app.state are per process. RedisRateLimiter coordinates decorated route quotas and ServerSideSessions stores revocable sessions across workers. Security-failure and WebSocket message throttles remain process-local. See Shared Quotas and Sessions for namespace consistency, storage failure behavior, and migration requirements.

Optional extras:

uv add flasgo --extra metrics  # Prometheus metrics
uv add flasgo --extra db       # Alembic migration commands
uv add flasgo --extra jwt      # Strict HS256 helpers
uv add flasgo --extra otel     # OpenTelemetry tracing and OTLP/HTTP export
uv add flasgo --extra redis    # Shared Redis/Valkey quotas and sessions

For complete commands and examples, see CLI and Migrations and Observability.

Sources:

• README.md
• pyproject.toml