Configuration Reference

Generated projects use pydantic-settings and read values from .env. Start from:

cp .env.example .env

Settings are resolved through get_settings(), which is cached for normal runtime use. The generated FastAPI application calls get_settings() inside create_app(), and the local runner calls it inside run.py's main(). This avoids import-time configuration in app.py.

When tests or scripts change environment variables in-process, clear the settings cache before creating the app:

from shop_api.app import create_app
from shop_api.settings import get_settings

get_settings.cache_clear()
app = create_app()

Application

Setting	Default	Purpose
APP_NAME	project name	FastAPI title and status service name
APP_ENV	development	Runtime environment label
APP_DEBUG	true	FastAPI debug mode
API_V1_PREFIX	/api/v1	Prefix for the generated API router

Database

Setting	Default	Purpose
DATABASE_URL	sqlite:///./poleposition.db	SQLAlchemy database URL
POSTGRES_DB	app	Local Docker PostgreSQL database
POSTGRES_USER	postgres	Local Docker PostgreSQL user
POSTGRES_PASSWORD	postgres	Local Docker PostgreSQL password
POSTGRES_PORT	5432	Host port for local Docker PostgreSQL

Projects generated with polepos start --db none omit DATABASE_URL, PostgreSQL settings, SQLAlchemy, and Alembic wiring. Projects generated with --db postgres start with a PostgreSQL DATABASE_URL instead of the SQLite default.

Use Alembic for schema changes:

polepos db revision -m "add customers table"
polepos db upgrade

For the full workflow, see Database and Migrations.

Runtime

Setting	Default	Purpose
APP_HOST	127.0.0.1	Host passed to Uvicorn
APP_PORT	8000	Port passed to Uvicorn
APP_RELOAD	true	Uvicorn reload mode
UVICORN_WORKERS	1	Worker process count
UVICORN_ACCESS_LOG	true	Uvicorn access log toggle
UVICORN_PROXY_HEADERS	true	Trust proxy headers
UVICORN_FORWARDED_ALLOW_IPS	127.0.0.1	Allowed proxy IPs
UVICORN_SERVER_HEADER	true	Emit server header
UVICORN_DATE_HEADER	true	Emit date header
UVICORN_TIMEOUT_KEEP_ALIVE	5	Keep-alive timeout
UVICORN_BACKLOG	2048	Socket backlog

Optional integer or boolean-like values can be left commented in .env.example until needed. Required generated values should stay active. polepos check treats commented required settings and env keys as missing so disabled examples do not accidentally satisfy the project contract.

run.py is the preferred local process entrypoint. It reads these values when main() runs and starts Uvicorn with <package>.main:app. main.py exposes the ASGI app, while app.py keeps the reusable create_app() factory.

Logging

Setting	Default	Purpose
LOG_LEVEL	INFO	Python logging level
LOG_FORMAT	text	text or json

Use json for structured production logs:

LOG_FORMAT=json

CORS

Setting	Default	Purpose
CORS_ENABLED	true	Enable FastAPI CORS middleware
CORS_ALLOW_ORIGINS	local frontend origins	Allowed origins
CORS_ALLOW_ORIGIN_REGEX	empty	Optional origin regex
CORS_ALLOW_CREDENTIALS	true	Allow credentials
CORS_ALLOW_METHODS	common HTTP methods	Allowed methods
CORS_ALLOW_HEADERS	auth and content headers	Allowed headers
CORS_EXPOSE_HEADERS	X-Request-ID	Exposed response headers
CORS_MAX_AGE	600	Browser preflight cache seconds

List settings accept JSON arrays:

CORS_ALLOW_ORIGINS=["https://app.example.com"]

Authentication

Setting	Default	Purpose
AUTH_SECRET_KEY	change-me-in-production	JWT signing secret
AUTH_ALGORITHM	HS256	JWT algorithm
AUTH_ACCESS_TOKEN_EXPIRE_MINUTES	60	Access token lifetime
AUTH_ISSUER	project name	Expected JWT issuer

Change AUTH_SECRET_KEY before deployment.

Kafka

Kafka settings are added by:

polepos add integration kafka

Important values:

• KAFKA_ENABLED
• KAFKA_BOOTSTRAP_SERVERS
• KAFKA_CLIENT_ID
• KAFKA_DEFAULT_TOPIC
• KAFKA_GROUP_ID
• KAFKA_REQUEST_TIMEOUT_MS

KAFKA_COMPRESSION_TYPE is generated as an optional commented example. Leave it commented until compression is needed; keep required values such as KAFKA_BOOTSTRAP_SERVERS active.

RabbitMQ

RabbitMQ settings are added by:

polepos add integration rabbitmq

Important values:

• RABBITMQ_ENABLED
• RABBITMQ_URL
• RABBITMQ_CLIENT_ID
• RABBITMQ_EXCHANGE
• RABBITMQ_DEFAULT_ROUTING_KEY
• RABBITMQ_DEFAULT_QUEUE
• RABBITMQ_PREFETCH_COUNT

Redis

Redis settings are added by:

polepos add integration redis

Important values:

• REDIS_ENABLED
• REDIS_URL
• REDIS_CLIENT_NAME
• REDIS_KEY_PREFIX
• REDIS_SOCKET_TIMEOUT_SECONDS

RQ

RQ settings are added by:

polepos add integration rq

Important values:

• RQ_ENABLED
• RQ_REDIS_URL
• RQ_DEFAULT_QUEUE
• RQ_WORKER_NAME
• RQ_JOB_TIMEOUT_SECONDS
• RQ_RESULT_TTL_SECONDS

LLM

LLM settings are added when an AI prompt module is generated:

polepos add module assistant --template ai-prompt

Important values:

• LLM_PROVIDER
• LLM_MODEL
• LLM_API_KEY
• LLM_BASE_URL
• LLM_TIMEOUT_SECONDS
• LLM_TEMPERATURE
• LLM_MAX_TOKENS

LLM_MAX_TOKENS is generated as an optional commented example. Required values such as LLM_PROVIDER, LLM_MODEL, and LLM_API_KEY should remain active in .env.example, even when the value is empty.