Configuration

All Kartograph settings are managed via environment variables. The application validates these settings at startup using Pydantic.

Tip

For local development, the docker compose config will automatically load Kartograph API configuration environment variables from env/api.env.

Database

Configuration for the PostgreSQL database and Apache AGE graph extension.

Variable	Required	Default	Description
KARTOGRAPH_DB_HOST str	Optional	localhost	Database host
KARTOGRAPH_DB_PORT int	Optional	5432	Database port
KARTOGRAPH_DB_DATABASE str	Optional	kartograph	Database name
KARTOGRAPH_DB_USERNAME str	Optional	kartograph	Database username
KARTOGRAPH_DB_PASSWORD Secret	Required	—	Database password
KARTOGRAPH_DB_GRAPH_NAME str	Optional	kartograph_graph	Name of the AGE graph
KARTOGRAPH_DB_POOL_MIN_CONNECTIONS int	Optional	2	Minimum connections in pool
KARTOGRAPH_DB_POOL_MAX_CONNECTIONS int	Optional	10	Maximum connections in pool
KARTOGRAPH_DB_SSL_MODE Literal	Optional	prefer	SSL mode for asyncpg connections (disable, allow, prefer, require, verify-ca, verify-full)

Authentication (OIDC)

Settings for connecting to an OpenID Connect provider like Keycloak or Auth0.

Variable	Required	Default	Description
KARTOGRAPH_OIDC_ISSUER_URL str	Optional	http://localhost:8080/realms/kartograph	OIDC issuer URL (e.g., Keycloak realm URL)
KARTOGRAPH_OIDC_CLIENT_ID str	Optional	kartograph-api	OIDC client ID for the API
KARTOGRAPH_OIDC_CLIENT_SECRET Secret	Required	—	OIDC client secret
KARTOGRAPH_OIDC_SWAGGER_CLIENT_ID str	Optional	kartograph-swagger	OIDC client ID for Swagger UI (public client)
KARTOGRAPH_OIDC_USER_ID_CLAIM str	Optional	sub	JWT claim to use for user ID
KARTOGRAPH_OIDC_USERNAME_CLAIM str	Optional	preferred_username	JWT claim to use for username
KARTOGRAPH_OIDC_AUDIENCE str | None	Optional	—	Expected audience claim (defaults to client_id if None)

CORS

Cross-Origin Resource Sharing settings for the API.

Variable	Required	Default	Description
KARTOGRAPH_CORS_ORIGINS list	Optional	[]	List of allowed origins for CORS
KARTOGRAPH_CORS_ALLOW_CREDENTIALS bool	Optional	true	Allow credentials in CORS requests
KARTOGRAPH_CORS_ALLOW_METHODS list	Optional	GET, POST, PUT, DELETE, OPTIONS, PATCH	Allowed HTTP methods for CORS
KARTOGRAPH_CORS_ALLOW_HEADERS list	Optional	*	Allowed headers for CORS

IAM & Tenants

Identity and Multi-tenancy configuration.

Variable	Required	Default	Description
KARTOGRAPH_IAM_DEFAULT_TENANT_NAME str	Optional	default	Default tenant name for single-tenant mode

Outbox Worker

Settings for the background worker that processes the transactional outbox.

Variable	Required	Default	Description
KARTOGRAPH_OUTBOX_ENABLED bool	Optional	true	Enable the outbox worker
KARTOGRAPH_OUTBOX_POLL_INTERVAL_SECONDS int	Optional	30	How often to poll for unprocessed entries
KARTOGRAPH_OUTBOX_BATCH_SIZE int	Optional	100	Maximum entries to process per batch
KARTOGRAPH_OUTBOX_MAX_RETRIES int	Optional	5	Maximum retry attempts before moving to DLQ

SpiceDB

Settings for the SpiceDB authorization service (gRPC).

Tip

For local development, the docker compose config will automatically load SpiceDB config environment variables from env/spicedb.env.

Variable	Required	Default	Description
SPICEDB_ENDPOINT str	Optional	localhost:50051	SpiceDB gRPC endpoint
SPICEDB_PRESHARED_KEY Secret	Required	—	Pre-shared key for authentication
SPICEDB_USE_TLS bool	Optional	true	Use TLS for connection (true for production, false for local dev)
SPICEDB_CERT_PATH str | None	Optional	—	Path to custom TLS root certificate (for self-signed certs)