Settings¶

Configure your Aksara application using the settings system.

Overview¶

Aksara provides a flexible configuration system that supports:

Environment variables — For production deployments
Explicit configuration — For development and testing
Sensible defaults — Minimal setup required

Configuration Methods¶

Method 1: Environment Variables¶

The simplest approach for production:

# .env file
DATABASE_URL=postgresql://user:pass@localhost:5432/myapp
AKSARA_DEBUG=false
AKSARA_LOG_LEVEL=INFO
AKSARA_POOL_MAX_SIZE=20

Aksara automatically loads from environment variables prefixed with AKSARA_.

Method 2: Explicit Configuration¶

For programmatic control, use configure():

from aksara import configure

configure(
    database_url="postgresql://localhost/myapp",
    debug=True,
    pool_min_size=5,
    pool_max_size=20,
    log_level="DEBUG",
    installed_apps=[
        "aksara.contrib.auth",
        "aksara.contrib.admin",
        "app",
    ],
)

Method 3: Settings File¶

Create a settings.py file and import it early:

# settings.py
import os
from aksara import configure

configure(
    database_url=os.getenv("DATABASE_URL"),
    debug=os.getenv("AKSARA_DEBUG", "false").lower() == "true",
    pool_min_size=int(os.getenv("AKSARA_POOL_MIN_SIZE", "5")),
    pool_max_size=int(os.getenv("AKSARA_POOL_MAX_SIZE", "20")),
)

# main.py
import settings  # Load configuration first
from aksara import Aksara

app = Aksara(title="My App")

Available Settings¶

Database Settings¶

Setting	Type	Default	Description
`database_url`	`str`	`None`	PostgreSQL connection URL
`pool_min_size`	`int`	`5`	Minimum connections in pool
`pool_max_size`	`int`	`20`	Maximum connections in pool

configure(
    database_url="postgresql://user:pass@localhost:5432/myapp",
    pool_min_size=5,
    pool_max_size=20,
)

Debug & Logging¶

Setting	Type	Default	Description
`debug`	`bool`	`False`	Enable debug mode
`log_level`	`str`	`"INFO"`	Logging level
`log_requests`	`bool`	`True`	Log HTTP requests
`log_json`	`bool`	`False`	Use JSON log format

configure(
    debug=True,
    log_level="DEBUG",
    log_requests=True,
    log_json=False,
)

Debug Mode in Production

Never enable debug=True in production. Debug mode exposes detailed error information and enables development features.

Application Metadata¶

Setting	Type	Default	Description
`app_title`	`str`	`None`	Application title
`app_version`	`str`	`None`	Application version

configure(
    app_title="My Blog API",
    app_version="1.0.0",
)

Migrations¶

Setting	Type	Default	Description
`migrations_dir`	`str`	`"migrations"`	Path to migrations directory

configure(
    migrations_dir="db/migrations",
)

Installed Apps¶

Setting	Type	Default	Description
`installed_apps`	`list[str]`	See below	Apps to auto-load
`apps`	`list[str]`	`["app"]`	Legacy app list

Default installed_apps:

[
    "aksara.contrib.auth",   # User authentication
    "aksara.contrib.admin",  # Admin interface
    "app",                   # Default user app
]

AI Features¶

Setting	Type	Default	Description
`ai_enabled`	`bool`	`False`	Enable AI endpoints
`mcp_enabled`	`bool`	`False`	Enable MCP protocol
`ai_debug_enabled`	`bool`	`True`	Enable AI debug suggestions

mcp_enabled and ai_enabled default to False for explicit opt-in. In practice, enabling ai_enabled=True is sufficient — MCP tool generation activates automatically. Set both to True if you need granular control.

configure(
    ai_enabled=True,
    mcp_enabled=True,
    ai_debug_enabled=True,
)

Environment Variables Reference¶

All settings can be set via environment variables:

Environment Variable	Setting	Example
`DATABASE_URL`	`database_url`	`postgresql://...`
`AKSARA_DATABASE_URL`	`database_url` (priority)	`postgresql://...`
`AKSARA_DEBUG`	`debug`	`true`, `false`
`AKSARA_LOG_LEVEL`	`log_level`	`DEBUG`, `INFO`, `WARNING`
`AKSARA_LOG_REQUESTS_DISABLED`	`log_requests`	`true` to disable
`AKSARA_LOG_JSON`	`log_json`	`true`, `false`
`AKSARA_POOL_MIN_SIZE`	`pool_min_size`	`5`
`AKSARA_POOL_SIZE`	`pool_max_size`	`20`
`AKSARA_POOL_MAX_SIZE`	`pool_max_size`	`20`
`AKSARA_APP_TITLE`	`app_title`	`My App`
`AKSARA_APP_VERSION`	`app_version`	`1.0.0`
`AKSARA_MIGRATIONS_DIR`	`migrations_dir`	`migrations`

Accessing Settings¶

After configuration, access settings via the settings object:

from aksara import settings

# Access any setting
print(settings.database_url)
print(settings.debug)
print(settings.pool_max_size)
print(settings.installed_apps)

Configuration Priority¶

Settings are resolved in this order (highest priority first):

Explicit configure() call — Programmatic settings
Environment variables — AKSARA_* prefixed
Built-in defaults — Sensible fallbacks

Example:

# .env
AKSARA_DEBUG=false

# settings.py
configure(debug=True)  # This wins - explicit configuration

from aksara import settings
print(settings.debug)  # True

Environment-Specific Configuration¶

Development¶

# settings_dev.py
from aksara import configure

configure(
    database_url="postgresql://localhost/myapp_dev",
    debug=True,
    log_level="DEBUG",
    log_requests=True,
)

Testing¶

# settings_test.py
from aksara import configure

configure(
    database_url="postgresql://localhost/myapp_test",
    debug=True,
    log_level="WARNING",
    log_requests=False,
)

Production¶

# settings_prod.py
import os
from aksara import configure

configure(
    database_url=os.environ["DATABASE_URL"],  # Required
    debug=False,
    log_level="INFO",
    log_json=True,  # Structured logs for log aggregation
    pool_min_size=10,
    pool_max_size=50,
)

Aksara App Constructor Settings¶

The Aksara class accepts additional settings at initialization:

from aksara import Aksara

app = Aksara(
    # Database (overrides configure())
    database_url="postgresql://localhost/myapp",
    min_pool_size=5,
    max_pool_size=20,

    # FastAPI settings
    title="My API",
    description="API description",
    version="1.0.0",
    debug=True,

    # OpenAPI
    openapi_url="/openapi.json",
    docs_url="/docs",
    redoc_url="/redoc",

    # Admin
    enable_admin=True,

    # Auto-discovery
    auto_discover_views=True,
    views_module="app.views",

    # Middleware
    middlewares=[
        (RequestIDMiddleware, {}),
        (LoggingMiddleware, {}),
    ],
)

Best Practices¶

Use `.env` Files for Secrets¶

Never commit secrets to version control:

# .gitignore
.env
.env.local
.env.production

Validate Required Settings¶

import os
from aksara import configure

DATABASE_URL = os.getenv("DATABASE_URL")
if not DATABASE_URL:
    raise ValueError("DATABASE_URL environment variable is required")

configure(database_url=DATABASE_URL)

Type Hints for IDE Support¶

from aksara.conf import Settings

def get_database_url(settings: Settings) -> str:
    if settings.database_url is None:
        raise ValueError("Database URL not configured")
    return settings.database_url

Database Setup — Configure PostgreSQL
Settings Reference — Complete settings API
Running Your App — Development and production