Environment Variables
Complete reference of all environment variables available when self-hosting Kitbase. All variables are configured in your .env file.
Required
| Variable | Description |
|---|---|
JWT_SECRET | Secret key for JWT tokens. Generate with openssl rand -base64 32 |
DATABASE_PASSWORD | MySQL root password |
App Settings
| Variable | Default | Description |
|---|---|---|
PORT | 80 | Port to expose the dashboard and API |
APP_DOMAIN | localhost | Your domain name (without protocol) |
APP_PROTOCOL | http | http or https |
SUPPORT_EMAIL | support@localhost | Support contact email shown to users |
Email
Required for password resets, invitations, and notifications. Kitbase supports three email providers: SMTP, AWS SES, and Resend. See the Email Providers guide for setup details and switching instructions.
Common
| Variable | Default | Description |
|---|---|---|
MAIL_PROVIDER | smtp | Email provider: smtp, ses, or resend |
MAIL_FROM | noreply@localhost | Sender email address |
MAIL_INVITATION_SUBJECT | You've been invited to join an organization | Invitation email subject line |
MAIL_BASE_URL | http://localhost | Base URL used in email links |
SMTP (when MAIL_PROVIDER=smtp)
| Variable | Default | Description |
|---|---|---|
SMTP_HOST | — | SMTP server hostname |
SMTP_PORT | 587 | SMTP server port |
SMTP_USERNAME | — | SMTP username |
SMTP_PASSWORD | — | SMTP password |
SMTP_AUTH | true | Enable SMTP authentication |
SMTP_STARTTLS | true | Enable STARTTLS |
SMTP_STARTTLS_REQUIRED | true | Require STARTTLS |
SMTP_CONNECTION_TIMEOUT | 5000 | Connection timeout in ms |
SMTP_TIMEOUT | 5000 | Read timeout in ms |
SMTP_WRITE_TIMEOUT | 5000 | Write timeout in ms |
AWS SES (when MAIL_PROVIDER=ses)
| Variable | Default | Description |
|---|---|---|
SES_ACCESS_KEY | — | AWS access key ID |
SES_SECRET_KEY | — | AWS secret access key |
SES_REGION | us-east-1 | AWS region for SES |
SES_ENDPOINT | — | Custom SES endpoint (optional, for testing with LocalStack) |
TIP
The MAIL_FROM address must be verified in your AWS SES account. If your account is in the SES sandbox, recipient addresses must also be verified.
Resend (when MAIL_PROVIDER=resend)
| Variable | Default | Description |
|---|---|---|
RESEND_API_KEY | — | Resend API key (starts with re_) |
TIP
The MAIL_FROM address must use a domain you've verified in your Resend dashboard. For testing, you can use onboarding@resend.dev.
Database (MySQL)
TIP
You only need to change these if you're using an external MySQL instance instead of the bundled container.
| Variable | Default | Description |
|---|---|---|
DATABASE_URL | jdbc:mysql://mysql:3306/flyway_db?... | JDBC connection URL |
DATABASE_USERNAME | root | MySQL username |
DATABASE_PASSWORD | root | MySQL password |
ClickHouse
| Variable | Default | Description |
|---|---|---|
CLICKHOUSE_URL | jdbc:clickhouse://clickhouse:8123/analytics | JDBC connection URL |
CLICKHOUSE_USERNAME | default | ClickHouse username |
CLICKHOUSE_PASSWORD | clickhouse123 | ClickHouse password |
Redis
| Variable | Default | Description |
|---|---|---|
REDIS_HOST | redis | Redis hostname |
REDIS_PORT | 6379 | Redis port |
Optional
OAuth
Google
| Variable | Default | Description |
|---|---|---|
OAUTH_GOOGLE_CLIENT_ID | — | Google OAuth client ID |
OAUTH_GOOGLE_CLIENT_SECRET | — | Google OAuth client secret |
OAUTH_GOOGLE_REDIRECT_URI | http://localhost/api/auth/oauth/google/callback | OAuth callback URL |
OAUTH_GOOGLE_SCOPES | openid email profile | OAuth scopes to request |
GitHub
| Variable | Default | Description |
|---|---|---|
OAUTH_GITHUB_CLIENT_ID | — | GitHub OAuth client ID |
OAUTH_GITHUB_CLIENT_SECRET | — | GitHub OAuth client secret |
OAUTH_GITHUB_REDIRECT_URI | http://localhost/api/auth/oauth/github/callback | OAuth callback URL |
OAUTH_GITHUB_SCOPES | user:email | OAuth scopes to request |
Slack Integration
| Variable | Default | Description |
|---|---|---|
SLACK_CLIENT_ID | — | Slack app client ID |
SLACK_CLIENT_SECRET | — | Slack app client secret |
SLACK_REDIRECT_URI | http://localhost/api/integrations/slack/oauth/callback | Slack OAuth callback URL |
Storage
Kitbase uses file storage for OTA update files. By default, files are stored locally. Configure S3 for cloud storage.
| Variable | Default | Description |
|---|---|---|
STORAGE_LOCAL_ROOT_PATH | ./storage | Local file storage directory |
STORAGE_LOCAL_BASE_URL | http://localhost/api/storage | Public URL for local storage |
S3_BUCKET_NAME | — | S3 bucket name (enables S3 storage) |
S3_REGION | us-east-1 | AWS region (use auto for Cloudflare R2) |
S3_ACCESS_KEY | — | S3 access key (setting this enables S3 storage) |
S3_SECRET_KEY | — | S3 secret key |
S3_ENDPOINT | — | Custom S3-compatible API endpoint. Required for non-AWS providers (R2, MinIO, Spaces, GCS). See S3-Compatible Storage |
S3_PUBLIC_URL | — | Custom public URL prefix for stored files. Overrides the default AWS URL format |
Error Handling
| Variable | Default | Description |
|---|---|---|
ERROR_INCLUDE_STACKTRACE | false | Include stack traces in API error responses |
ERROR_NOTIFICATION_ENABLED | false | Send email notifications on errors |
ERROR_NOTIFICATION_EMAIL | — | Email address for error notifications |
Logging
| Variable | Default | Description |
|---|---|---|
LOG_LEVEL_APP | INFO | Application log level |
LOG_LEVEL_JOOQ | INFO | Database query log level |
LOG_LEVEL_SECURITY | WARN | Security log level |