Skip to content

Configuration

Jump to bottom
John R. D'Orazio edited this page Feb 18, 2026 · 4 revisions

Configuration

The OntoKit API is configured via environment variables. These can be set in a .env file in the project root.

Deployment Modes

OntoKit supports two deployment configurations:

Mode Compose File Use Case
Full Docker compose.yaml Quick start, CI/CD, testing
Hybrid compose.prod.yaml Development with IDE debugging, production

Full Docker Mode (compose.yaml)

All services run in Docker containers, including the API:

docker compose up -d

The API container uses Docker hostnames for service discovery:

  • Database: postgresql+asyncpg://ontokit:ontokit@postgres:5432/ontokit
  • Redis: redis://redis:6379/0
  • MinIO: minio:9000

Hybrid Mode (compose.prod.yaml)

Infrastructure runs in Docker, API runs on host:

docker compose -f compose.prod.yaml up -d

The API uses localhost to connect to Docker containers:

  • Database: postgresql+asyncpg://ontokit:ontokit@localhost:5432/ontokit
  • Redis: redis://localhost:6379/0
  • MinIO: localhost:9000

Environment Variables Reference

Application Settings

Variable Default Description
APP_ENV development Environment: development, staging, production
DEBUG false Enable debug mode (verbose logging)
SECRET_KEY (required) Secret key for cryptographic operations. Use a random 32+ character string in production.

Server Settings

Variable Default Description
HOST 0.0.0.0 Host to bind the server to
PORT 8000 Port to bind the server to

Database (PostgreSQL)

Variable Default Description
DATABASE_URL postgresql+asyncpg://ontokit:ontokit@localhost:5432/ontokit PostgreSQL connection URL

Connection URL Format:

postgresql+asyncpg://username:password@host:port/database

Note: The stack uses a single PostgreSQL instance on port 5432 with separate databases for Zitadel (zitadel) and OntoKit (ontokit).

Redis

Variable Default Description
REDIS_URL redis://localhost:6379/0 Redis connection URL

MinIO / S3 Object Storage

Variable Default Description
MINIO_ENDPOINT localhost:9000 MinIO server endpoint
MINIO_ACCESS_KEY minio Access key (username)
MINIO_SECRET_KEY minio123 Secret key (password)
MINIO_BUCKET ontokit Default bucket name
MINIO_SECURE false Use HTTPS (true/false)

Zitadel Authentication

Variable Default Description
ZITADEL_ISSUER http://localhost:8080 Zitadel issuer URL (used for token validation)
ZITADEL_INTERNAL_URL (same as issuer) Internal URL for reaching Zitadel (Docker network)
ZITADEL_CLIENT_ID (empty) OAuth2 client ID
ZITADEL_CLIENT_SECRET (empty) OAuth2 client secret (for confidential clients)

Note: When running in Full Docker mode, ZITADEL_INTERNAL_URL is set to http://zitadel:8080 to allow the API container to reach Zitadel via Docker networking. The ZITADEL_ISSUER remains http://localhost:8080 to match the issuer claim in JWT tokens.

Tip: Run ./scripts/setup-zitadel.sh --update-env to automatically create OIDC applications and update .env files with credentials. See Authentication for details.

CORS (Cross-Origin Resource Sharing)

Variable Default Description
CORS_ORIGINS ["http://localhost:3000"] Allowed origins (JSON array format)

Example:

CORS_ORIGINS=["http://localhost:3000","http://localhost:5173","https://app.ontokit.dev"]

GitHub Integration (Optional)

Variable Default Description
GITHUB_APP_ID (empty) GitHub App ID
GITHUB_APP_PRIVATE_KEY (empty) GitHub App private key (PEM format)

Infrastructure Settings (compose.prod.yaml)

These variables customize the infrastructure services when using compose.prod.yaml:

PostgreSQL

Variable Default Description
POSTGRES_PASSWORD postgres PostgreSQL superuser password
POSTGRES_PORT 5432 Host port mapping

Redis

Variable Default Description
REDIS_PASSWORD (none) Optional Redis password
REDIS_PORT 6379 Host port mapping

MinIO

Variable Default Description
MINIO_ROOT_USER minio MinIO admin username
MINIO_ROOT_PASSWORD minio123 MinIO admin password
MINIO_API_PORT 9000 S3 API port
MINIO_CONSOLE_PORT 9001 Web console port

Zitadel

Variable Default Description
ZITADEL_MASTERKEY MasterkeyNeedsToHave32Characters 32-character encryption master key
ZITADEL_DOMAIN localhost External domain for Zitadel
ZITADEL_SECURE false Enable HTTPS for external connections
ZITADEL_TLS false Enable TLS on Zitadel server
ZITADEL_PORT 8080 Zitadel API port
ZITADEL_LOGIN_PORT 8081 Login UI port
ZITADEL_URL http://localhost:8080 Full Zitadel URL
ZITADEL_LOGIN_URL http://localhost:8081 Login UI URL
ZITADEL_DB_PASSWORD zitadel Zitadel database user password
ZITADEL_ORG_NAME OntoKit Initial organization name
ZITADEL_ADMIN_USER admin Admin username
ZITADEL_ADMIN_PASSWORD Admin123! Admin password
ZITADEL_REQUIRE_PASSWORD_CHANGE true Force password change on first login
ZITADEL_LOG_LEVEL info Log level: debug, info, warn, error
ZITADEL_ACCESS_LOG false Enable access logging

Example Configuration Files

Development - Hybrid Mode (.env)

For running API on host with Docker infrastructure:

# Application
APP_ENV=development
DEBUG=true
SECRET_KEY=dev-secret-key-change-in-production

# Server
HOST=0.0.0.0
PORT=8000

# Database (connects to shared PostgreSQL container)
DATABASE_URL=postgresql+asyncpg://ontokit:ontokit@localhost:5432/ontokit

# Redis
REDIS_URL=redis://localhost:6379/0

# MinIO
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=minio123
MINIO_BUCKET=ontokit
MINIO_SECURE=false

# Zitadel
ZITADEL_ISSUER=http://localhost:8080
ZITADEL_CLIENT_ID=your-client-id
ZITADEL_CLIENT_SECRET=your-client-secret

# CORS
CORS_ORIGINS=["http://localhost:3000","http://localhost:3001"]

Production (.env.production)

# Application
APP_ENV=production
DEBUG=false
SECRET_KEY=your-very-long-random-production-secret-key-here

# Server
HOST=0.0.0.0
PORT=8000

# Database
DATABASE_URL=postgresql+asyncpg://ontokit:secure-password@db.example.com:5432/ontokit

# Redis
REDIS_URL=redis://:redis-password@redis.example.com:6379/0

# MinIO / S3
MINIO_ENDPOINT=s3.example.com
MINIO_ACCESS_KEY=production-access-key
MINIO_SECRET_KEY=production-secret-key
MINIO_BUCKET=ontokit-prod
MINIO_SECURE=true

# Zitadel
ZITADEL_ISSUER=https://auth.example.com
ZITADEL_CLIENT_ID=production-client-id
ZITADEL_CLIENT_SECRET=production-client-secret

# CORS
CORS_ORIGINS=["https://app.example.com"]

Production Infrastructure (.env for compose.prod.yaml)

# PostgreSQL
POSTGRES_PASSWORD=secure-postgres-password
POSTGRES_PORT=5432

# Redis
REDIS_PASSWORD=secure-redis-password
REDIS_PORT=6379

# MinIO
MINIO_ROOT_USER=minio
MINIO_ROOT_PASSWORD=secure-minio-password
MINIO_API_PORT=9000
MINIO_CONSOLE_PORT=9001

# Zitadel
ZITADEL_MASTERKEY=your-32-character-master-key-here
ZITADEL_DOMAIN=auth.yourdomain.com
ZITADEL_SECURE=true
ZITADEL_TLS=true
ZITADEL_PORT=8080
ZITADEL_LOGIN_PORT=8081
ZITADEL_URL=https://auth.yourdomain.com
ZITADEL_LOGIN_URL=https://auth.yourdomain.com
ZITADEL_DB_PASSWORD=secure-zitadel-password
ZITADEL_ORG_NAME=YourOrganization
ZITADEL_ADMIN_USER=admin
ZITADEL_ADMIN_PASSWORD=secure-admin-password
ZITADEL_REQUIRE_PASSWORD_CHANGE=true
ZITADEL_LOG_LEVEL=info
ZITADEL_ACCESS_LOG=false

Generating a Secret Key

For production, generate a secure secret key:

# Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# OpenSSL
openssl rand -base64 32

Generating a Zitadel Master Key

The master key must be exactly 32 characters:

# Python
python -c "import secrets; print(secrets.token_urlsafe(24))"

# OpenSSL
openssl rand -base64 24

Configuration Validation

The application validates configuration on startup. If required variables are missing or invalid, you'll see an error message with details.

Next Steps

Getting Started

Development

Features

Help

Clone this wiki locally