> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veloiq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# VeloIQConfig: Complete Framework Configuration Reference

> Every VeloIQConfig field and corresponding environment variable for configuring database, auth, CORS, admin panel, and modules directory.

`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

<CodeGroup>
  ```python Explicit config object theme={null}
  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",
  ))
  ```

  ```python Environment variables only theme={null}
  # main.py — one line
  from veloiq_framework import create_veloiq_app

  app = create_veloiq_app()
  ```

  ```ini .env file theme={null}
  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
  ```
</CodeGroup>

***

## 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. |

<Note>
  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).
</Note>

## 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).                                                                     |

<Warning>
  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.
</Warning>

### 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. |

```python theme={null}
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

```ini theme={null}
# 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
```

***

<CardGroup cols={2}>
  <Card title="Python API" icon="python" href="/reference/python-api">
    Full reference for all public symbols exported from `veloiq_framework`.
  </Card>

  <Card title="CRUD Router" icon="route" href="/reference/crud-router">
    Auto-generated endpoint reference and query parameter details.
  </Card>
</CardGroup>