VeloIQConfig: Complete Framework Configuration Reference

VeloIQConfig is a Python dataclass accepted by create_veloiq_app(). Every field reads from an environment variable when not set explicitly, so you can configure the application entirely through a .env file following 12-factor app conventions. Override individual fields in code when you need app-specific values that should not come from the environment.

Quick example

from veloiq_framework import create_veloiq_app, VeloIQConfig

app = create_veloiq_app(VeloIQConfig(
    title="Acme Admin",
    database_url="postgresql://user:pass@localhost/acme",
    cors_origins=["http://localhost:5173"],
    admin_title="Acme Back-Office",
))

# main.py — one line
from veloiq_framework import create_veloiq_app

app = create_veloiq_app()

DATABASE_URL=postgresql://user:pass@localhost/acme
CORS_ORIGINS=http://localhost:5173,https://app.acme.com
VELOIQ_MODULES_DIR=app/modules
AUTH_SECRET=your-secret-key

Database

Field	Env var	Default	Description
`database_url`	`DATABASE_URL`	—	SQLAlchemy database URL. Required. Supports SQLite (`sqlite:///./app.db`) and PostgreSQL (`postgresql://user:pass@host/db`).
`echo_sql`	`VELOIQ_ECHO_SQL`	`False`	Log all SQL statements to stdout. Useful for debugging; disable in production.
`create_tables_on_startup`	—	`True`	Call `SQLModel.metadata.create_all()` on startup. Set to `False` when managing schema with Alembic migrations.

Application

Field	Env var	Default	Description
`title`	—	`"VeloIQ App"`	FastAPI application title shown in `/docs` and the admin panel.
`modules_dir`	`VELOIQ_MODULES_DIR`	`"app/modules"`	Path to the modules directory, relative to the working directory. The framework discovers `models.py`, `api.py`, `custom_api.py`, and `admin/admin_views.py` inside each sub-folder.
`static_dir`	—	`None`	Directory to mount at `/static`. When `None`, no static mount is added.

CORS

Field	Env var	Default	Description
`cors_origins`	`CORS_ORIGINS`	`["http://localhost:5173", "http://127.0.0.1:5173", "http://localhost:3000", "http://127.0.0.1:3000"]`	Allowed CORS origins. In the environment variable, supply a comma-separated list. The default permits the standard Vite and Create React App dev ports.

The default cors_origins value in the code differs from the documentation shorthand ["*"] — it permits the standard local dev ports. In production, always set CORS_ORIGINS explicitly to your frontend domain(s).

Auth

Field	Env var	Default	Description
`auth_enabled`	`VELOIQ_AUTH_DISABLED`	`True`	Enable JWT Bearer token middleware. Set `VELOIQ_AUTH_DISABLED=1` to disable auth enforcement (development only).
`auth_secret`	`AUTH_SECRET`	`"veloiq-dev-secret-change-me"`	Secret key used to sign and verify JWT tokens.
`auth_algorithm`	—	`"HS256"`	JWT signing algorithm.
`auth_token_expire_minutes`	`AUTH_TOKEN_EXPIRE_MINUTES`	`480`	Token validity in minutes (default 8 hours).

Never use the default auth_secret in production. Set AUTH_SECRET to a long, random string before deploying. Any deployment with the default secret is trivially forgeable.

Initial admin seed credentials

These fields control the default admin user created on first startup. Once the user exists in the database, changing them has no effect.

Field	Env var	Default	Description
`admin_username`	`VELOIQ_ADMIN_USERNAME`	`"admin"`	Username for the seeded admin account.
`admin_password`	`VELOIQ_ADMIN_PASSWORD`	`"admin"`	Password for the seeded admin account. Change before first deployment.

Admin panel

Field	Env var	Default	Description
`admin_title`	—	Same as `title`	Title shown in the SQLAdmin back-office at `/admin/`.
`admin_logo_url`	—	`None`	URL of the logo image displayed in the admin panel header.
`admin_templates_dir`	—	`None`	Path to a custom Jinja2 templates directory for SQLAdmin overrides.

Roles

Field	Env var	Default	Description
`roles`	—	`DEFAULT_ROLES`	List of `RoleDef` objects upserted to the database on startup. Defaults to the built-in Admin, Manager, and Viewer presets. Replace or extend this list to introduce application-specific roles.

from veloiq_framework import (
    create_veloiq_app, VeloIQConfig,
    RoleDef, ALL_METHODS, WRITE_METHODS, READ_METHODS,
)

app = create_veloiq_app(VeloIQConfig(
    roles=[
        RoleDef("Admin",   ALL_METHODS,   "Full access",            is_preset=True),
        RoleDef("Manager", WRITE_METHODS, "Create/edit, no delete", is_preset=True),
        RoleDef("Viewer",  READ_METHODS,  "Read-only",              is_preset=True),
        RoleDef("Auditor", READ_METHODS,  "External auditor",       is_preset=True),
    ],
))

ReBAC

Field	Env var	Default	Description
`rebac_enabled`	`VELOIQ_REBAC_ENABLED`	`False`	Enable row-level access control globally. Individual models still require the `@rebac` decorator.

Environment variable reference

# Required
DATABASE_URL=postgresql://user:password@localhost/dbname

# Application
VELOIQ_MODULES_DIR=app/modules

# CORS (comma-separated)
CORS_ORIGINS=http://localhost:5173,https://yourdomain.com

# Auth
VELOIQ_AUTH_DISABLED=0
AUTH_SECRET=your-secret-key-here
AUTH_TOKEN_EXPIRE_MINUTES=480

# ReBAC
VELOIQ_REBAC_ENABLED=0

# Database debugging
VELOIQ_ECHO_SQL=false

# Initial admin seed (first startup only)
VELOIQ_ADMIN_USERNAME=admin
VELOIQ_ADMIN_PASSWORD=admin

Python API

Full reference for all public symbols exported from veloiq_framework.

CRUD Router

Auto-generated endpoint reference and query parameter details.

CLI

Python API

React UI Library

VeloIQConfig: Complete Framework Configuration Reference

Quick example

Database

Application

CORS

Auth

Initial admin seed credentials

Admin panel

Roles

ReBAC

Environment variable reference

Python API

CRUD Router

​Quick example

​Database

​Application

​CORS

​Auth

​Initial admin seed credentials

​Admin panel

​Roles

​ReBAC

​Environment variable reference

Python API

CRUD Router

Quick example

Database

Application

CORS

Auth

Initial admin seed credentials

Admin panel

Roles

ReBAC

Environment variable reference