Environment Variables Reference
All environment variables used across Kuploy components, grouped by concern.
Licensing
| Variable | Description | Default | Required |
|---|
LICENSE_KEY | License key from kuploy.app | (none) | Yes (Cloud) |
LICENSE_HUB_URL | License hub URL | https://kuploy.app | No |
LICENSE_SYNC_INTERVAL_SECONDS | How often to sync usage with license hub | 300 (5 min) | No |
LICENSE_SYNC_RETRY_SECONDS | Retry interval on sync failure | 60 (1 min) | No |
LICENSE_KEY and LICENSE_HUB_URL can also be configured via the admin UI (Admin → Domains → License Hub Integration). UI-saved config takes precedence over environment variables and does not require a restart.
Stripe Billing
| Variable | Description | Default | Required |
|---|
STRIPE_SECRET_KEY | Stripe API secret key | (none) | Yes (Cloud) |
STRIPE_PUBLISHABLE_KEY | Stripe publishable key | (none) | Yes (Cloud) |
STRIPE_WEBHOOK_SECRET | Webhook signing secret | (none) | Yes (Cloud) |
Authentication
| Variable | Description | Default | Required |
|---|
BETTER_AUTH_SECRET | Authentication secret (32+ chars) | (none) | Yes (Cloud) |
PLATFORM_ADMIN_EMAIL | Email of the first platform admin | (none) | Recommended |
SMTP
| Variable | Description | Default | Required |
|---|
SMTP_HOST | SMTP server hostname | (none) | Recommended |
SMTP_PORT | SMTP port | 587 | No |
SMTP_USER | SMTP authentication username | (none) | If SMTP_HOST set |
SMTP_PASS | SMTP authentication password | (none) | If SMTP_HOST set |
SMTP_FROM | Sender email address | (none) | If SMTP_HOST set |
SMTP_FROM_NAME | Sender display name | Kuploy | No |
Database
| Variable | Description | Default | Required |
|---|
DATABASE_URL | PostgreSQL connection string | (none) | Yes |
REDIS_URL | Redis connection string | (none) | Yes |
Encryption
| Variable | Description | Default | Required |
|---|
APP_SECRET | Encryption key for admin-saved secrets (Stalwart token, registry password, Stripe keys, etc.). Must be the same across all replicas and deployments that share a database. | (none) | Yes (Cloud) |
If two deployments share a database but have different APP_SECRET values, encrypted fields saved by one can't be decrypted by the other. The admin UI surfaces a "token decryption failed" alert and falls back to environment variables. See Email Hosting for details.
Default Container Registry
| Variable | Description | Default | Required |
|---|
DEFAULT_REGISTRY_URL | Hostname of the container registry (e.g. registry.ceduth.dev) | (none) | If not set via admin UI |
DEFAULT_REGISTRY_USERNAME | Registry username (e.g. robot$kuploy+kuploy for Harbor) | (none) | If not set via admin UI |
DEFAULT_REGISTRY_PASSWORD | Registry password or robot-account token | (none) | If not set via admin UI |
DEFAULT_REGISTRY_IMAGE_PREFIX | Image namespace prefix (e.g. kuploy) | (none) | No |
Can also be configured via Admin → Default Registry (password encrypted in database). Admin UI settings take precedence.
Email Hosting (Stalwart)
| Variable | Description | Default | Required |
|---|
STALWART_API_URL | Stalwart management REST API URL (e.g. http://stalwart-api:8080) | (none) | If not set via admin UI |
STALWART_API_TOKEN | Stalwart API key (Bearer token from Directory → API Keys) | (none) | If not set via admin UI |
Can also be configured via Admin → Email Hosting (Stalwart) (token encrypted in database). Admin UI settings take precedence.
Status Page (kuploy-cloud)
| Variable | Description | Default | Required |
|---|
STATUS_PROBE_INTERVAL_SECONDS | How often the in-process probe scheduler runs (clamped 60–3600) | 300 (5 min) | No |
PLATFORM_STATUS_URL | Override URL for the upstream platform status feed. Set to empty string to hide the "Upstream platform" row entirely. | ${LICENSE_HUB_URL}/api/status | No |
Status Page (kuploy-app / licensing hub)
| Variable | Description | Default | Required |
|---|
REGISTRY_PROBE_URL | Hostname of the shared container registry to probe on the central status page (e.g. registry.ceduth.dev) | (none) | No |
REGISTRY_PROBE_USER | Registry username for the probe (read-only access is sufficient) | (none) | If REGISTRY_PROBE_URL set |
REGISTRY_PROBE_PASSWORD | Registry password / token for the probe | (none) | If REGISTRY_PROBE_URL set |
These are separate from kuploy-cloud's DEFAULT_REGISTRY_* because kuploy-app (Vercel) doesn't share kuploy-cloud's config. The probe only needs read access — a read-only robot account is ideal.
Application
| Variable | Description | Default | Required |
|---|
NEXT_PUBLIC_APP_URL | Public URL of the kuploy-cloud instance | (none) | Recommended |
PORT | Port the application listens on | 3000 | No |
NODE_ENV | Node.js environment | production | No |
Cron
| Variable | Description | Default | Required |
|---|
CRON_SECRET | Secret for authenticating cron job requests | (none) | If using cron |
Site Import API
| Variable | Description | Default | Required |
|---|
ADMIN_API_KEY | Admin API key for programmatic access (bypasses org scoping) | (none) | No |
ADMIN_API_KEY is for platform operators running migration scripts. Regular users should use API keys generated from Settings → API Keys instead.
Configuration Priority
When the same setting is available via both environment variable and the admin dashboard:
- Admin dashboard (stored encrypted in database) — highest priority
- Environment variable — fallback
This means you can override environment variables through the admin dashboard without restarting the application. See Admin Dashboard for details.