Environment Variables
=====================

Complete reference for all OpenPanel environment variables

This page documents all environment variables used by OpenPanel. Variables are organized by category. Most variables are optional and have sensible defaults.

For deployment-specific configuration, see the [deployment guides](https://openpanel.dev/docs/self-hosting/deploy-docker-compose)
.

[Database & Storage](https://openpanel.dev/docs/self-hosting/environment-variables#database--storage)

------------------------------------------------------------------------------------------------------

### [DATABASE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#database_url)

**Type**: `string`  
**Required**: Yes  
**Default**: None

PostgreSQL connection string for the main database.

**Example**:

    DATABASE_URL=postgres://user:password@localhost:5432/openpanel?schema=public

### [DATABASE\_URL\_DIRECT](https://openpanel.dev/docs/self-hosting/environment-variables#database_url_direct)

**Type**: `string`  
**Required**: No  
**Default**: Same as `DATABASE_URL`

Direct PostgreSQL connection string (bypasses connection pooling). Used for migrations and administrative operations.

**Example**:

    DATABASE_URL_DIRECT=postgres://user:password@localhost:5432/openpanel?schema=public

### [DATABASE\_URL\_REPLICA](https://openpanel.dev/docs/self-hosting/environment-variables#database_url_replica)

**Type**: `string`  
**Required**: No  
**Default**: Same as `DATABASE_URL`

Read replica connection string for read-heavy operations. If not set, uses the main database.

**Example**:

    DATABASE_URL_REPLICA=postgres://user:password@replica-host:5432/openpanel?schema=public

### [REDIS\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#redis_url)

**Type**: `string`  
**Required**: Yes  
**Default**: `redis://localhost:6379`

Redis connection string for caching and queue management.

**Example**:

    REDIS_URL=redis://localhost:6379
    # With password
    REDIS_URL=redis://:password@localhost:6379

### [CLICKHOUSE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_url)

**Type**: `string`  
**Required**: Yes  
**Default**: `http://localhost:8123/openpanel`

ClickHouse HTTP connection URL for analytics data storage.

**Example**:

    CLICKHOUSE_URL=http://localhost:8123/openpanel

### [CLICKHOUSE\_CLUSTER](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_cluster)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Enable ClickHouse cluster mode. Set to `true` or `1` if using a ClickHouse cluster.

**Example**:

    CLICKHOUSE_CLUSTER=true

### [CLICKHOUSE\_SETTINGS](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_settings)

**Type**: `string` (JSON)  
**Required**: No  
**Default**: `{}`

Additional ClickHouse settings as a JSON object.

**Example**:

    CLICKHOUSE_SETTINGS='{"max_execution_time": 300}'

### [CLICKHOUSE\_SETTINGS\_REMOVE\_CONVERT\_ANY\_JOIN](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_settings_remove_convert_any_join)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Remove `convert_any_join` from ClickHouse settings. Used for compatibility with certain ClickHouse versions. This needs to be set if you use any clickhouse version below 25!

[Application URLs](https://openpanel.dev/docs/self-hosting/environment-variables#application-urls)

---------------------------------------------------------------------------------------------------

### [API\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#api_url)

**Type**: `string`  
**Required**: Yes  
**Default**: None

Public API URL exposed to the browser. Used by the dashboard frontend and API service.

**Example**:

    API_URL=https://analytics.example.com/api

### [DASHBOARD\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#dashboard_url)

**Type**: `string`  
**Required**: Yes  
**Default**: None

Public dashboard URL exposed to the browser. Used by the dashboard frontend and API service.

**Example**:

    DASHBOARD_URL=https://analytics.example.com

### [API\_CORS\_ORIGINS](https://openpanel.dev/docs/self-hosting/environment-variables#api_cors_origins)

**Type**: `string` (comma-separated)  
**Required**: No  
**Default**: None

Additional CORS origins allowed for API requests. Comma-separated list of origins.

**Example**:

    API_CORS_ORIGINS=https://app.example.com,https://another-app.com

[Authentication & Security](https://openpanel.dev/docs/self-hosting/environment-variables#authentication--security)

--------------------------------------------------------------------------------------------------------------------

### [COOKIE\_SECRET](https://openpanel.dev/docs/self-hosting/environment-variables#cookie_secret)

**Type**: `string`  
**Required**: Yes  
**Default**: None

Secret key for encrypting session cookies. Generate a secure random string (32+ characters).

**Example**:

    # Generate with: openssl rand -base64 32
    COOKIE_SECRET=your-random-secret-here

Never use the default value in production! Always generate a unique secret.

### [COOKIE\_TLDS](https://openpanel.dev/docs/self-hosting/environment-variables#cookie_tlds)

**Type**: `string` (comma-separated)  
**Required**: No  
**Default**: None

Custom multi-part TLDs for cookie domain handling. Use this when deploying on domains with public suffixes that aren't recognized by default (e.g., `.my.id`, `.web.id`, `.co.id`).

**Example**:

    # For domains like abc.my.id
    COOKIE_TLDS=my.id
    
    # Multiple TLDs
    COOKIE_TLDS=my.id,web.id,co.id

This is required when using domain suffixes that are public suffixes (like `.co.uk`). Without this, the browser will reject authentication cookies. Common examples include Indonesian domains (`.my.id`, `.web.id`, `.co.id`).

### [CUSTOM\_COOKIE\_DOMAIN](https://openpanel.dev/docs/self-hosting/environment-variables#custom_cookie_domain)

**Type**: `string`  
**Required**: No  
**Default**: None

Override the automatic cookie domain detection and set a specific domain for authentication cookies. Useful when proxying the API through your main domain or when you need precise control over cookie scope.

**Example**:

    # Set cookies only on the main domain
    CUSTOM_COOKIE_DOMAIN=.example.com
    
    # Set cookies on a specific subdomain
    CUSTOM_COOKIE_DOMAIN=.app.example.com

When set, this completely bypasses the automatic domain parsing logic. The cookie will always be set as secure. Include a leading dot (`.`) to allow the cookie to be shared across subdomains.

### [DEMO\_USER\_ID](https://openpanel.dev/docs/self-hosting/environment-variables#demo_user_id)

**Type**: `string`  
**Required**: No  
**Default**: None

User ID for demo mode. When set, creates a demo session for testing.

**Example**:

    DEMO_USER_ID=user_1234567890

### [ALLOW\_REGISTRATION](https://openpanel.dev/docs/self-hosting/environment-variables#allow_registration)

**Type**: `boolean`  
**Required**: No  
**Default**: `false` (after first user is created)

Allow new user registrations. Set to `true` to enable public registration.

**Example**:

    ALLOW_REGISTRATION=true

Registration is automatically disabled after the first user is created. Set this to `true` to re-enable it.

### [ALLOW\_INVITATION](https://openpanel.dev/docs/self-hosting/environment-variables#allow_invitation)

**Type**: `boolean`  
**Required**: No  
**Default**: `true`

Allow user invitations. Set to `false` to disable invitation functionality.

**Example**:

    ALLOW_INVITATION=false

[AI Features](https://openpanel.dev/docs/self-hosting/environment-variables#ai-features)

-----------------------------------------------------------------------------------------

The in-app AI chat supports **OpenAI** and **Anthropic** models. Set one or both provider keys on the API service — the model picker in the chat UI automatically shows only the models whose provider has a key configured. If neither is set, the chat drawer still opens but shows setup instructions instead of suggestions.

Available models:

*   **OpenAI** — `GPT-4.1`, `GPT-4.1 mini`, `GPT-5.4 mini`
*   **Anthropic** — `Claude Haiku 4.5`, `Claude Sonnet 4.6`, `Claude Opus 4.6`

The AI assistant is optional. Without `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` set, every other OpenPanel feature continues to work normally.

### [OPENAI\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#openai_api_key)

**Type**: `string`  
**Required**: No  
**Default**: None

OpenAI API key. When set, the OpenAI models appear in the chat model picker.

**Example**:

    OPENAI_API_KEY=sk-your-openai-api-key-here

### [OPENAI\_BASE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#openai_base_url)

**Type**: `string`  
**Required**: No  
**Default**: OpenAI default API base URL

Override the OpenAI API base URL. Useful for proxies, gateways, Azure-compatible endpoints, or self-hosted OpenAI-compatible providers.

**Example**:

    OPENAI_BASE_URL=https://your-openai-compatible-endpoint.example.com/v1

### [OPENAI\_PROJECT](https://openpanel.dev/docs/self-hosting/environment-variables#openai_project)

**Type**: `string`  
**Required**: No  
**Default**: None

Optional OpenAI project identifier to send with requests.

**Example**:

    OPENAI_PROJECT=proj_1234567890

### [OPENAI\_ORGANIZATION](https://openpanel.dev/docs/self-hosting/environment-variables#openai_organization)

**Type**: `string`  
**Required**: No  
**Default**: None

Optional OpenAI organization identifier to send with requests.

**Example**:

    OPENAI_ORGANIZATION=org_1234567890

### [ANTHROPIC\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_api_key)

**Type**: `string`  
**Required**: No  
**Default**: None

Anthropic API key. When set, the Claude models appear in the chat model picker.

**Example**:

    ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here

### [ANTHROPIC\_BASE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_base_url)

**Type**: `string`  
**Required**: No  
**Default**: Anthropic default API base URL

Override the Anthropic API base URL. Useful for proxies, gateways, or Anthropic-compatible endpoints.

**Example**:

    ANTHROPIC_BASE_URL=https://your-anthropic-endpoint.example.com

### [ANTHROPIC\_TOKEN](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_token)

**Type**: `string`  
**Required**: No  
**Default**: None

Optional auth token sent to the Anthropic provider in addition to the API key. Use this only if your Anthropic-compatible gateway requires it.

**Example**:

    ANTHROPIC_TOKEN=your-auth-token

### [ANTHROPIC\_VERSION](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_version)

**Type**: `string`  
**Required**: No  
**Default**: Provider default

Override the Anthropic API version header sent with requests.

**Example**:

    ANTHROPIC_VERSION=2023-06-01

[Email](https://openpanel.dev/docs/self-hosting/environment-variables#email)

-----------------------------------------------------------------------------

### [RESEND\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#resend_api_key)

**Type**: `string`  
**Required**: No  
**Default**: None

Resend API key for sending transactional emails (password resets, invitations, etc.).

**Example**:

    RESEND_API_KEY=re_xxxxxxxxxxxxx

Get your API key from [resend.com](https://resend.com/)
. Make sure to verify your sender email domain.

### [EMAIL\_SENDER](https://openpanel.dev/docs/self-hosting/environment-variables#email_sender)

**Type**: `string`  
**Required**: No  
**Default**: `hello@openpanel.dev`

Email address used as the sender for transactional emails. Applies to both Resend and SMTP transports.

**Example**:

    EMAIL_SENDER=noreply@yourdomain.com

### [SMTP\_HOST](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_host)

**Type**: `string`  
**Required**: No  
**Default**: None

SMTP server hostname. When set, OpenPanel uses SMTP to send emails instead of Resend. Takes priority over `RESEND_API_KEY` if both are configured.

**Example**:

    SMTP_HOST=smtp.example.com

### [SMTP\_PORT](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_port)

**Type**: `number`  
**Required**: No  
**Default**: `587`

SMTP server port.

**Example**:

    SMTP_PORT=587

### [SMTP\_SECURE](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_secure)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Use TLS for the SMTP connection. Set to `true` when using port `465`.

**Example**:

    SMTP_SECURE=true

### [SMTP\_USER](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_user)

**Type**: `string`  
**Required**: No  
**Default**: None

SMTP authentication username. Leave unset if your server does not require authentication.

**Example**:

    SMTP_USER=smtp-user@example.com

### [SMTP\_PASS](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_pass)

**Type**: `string`  
**Required**: No  
**Default**: None

SMTP authentication password.

**Example**:

    SMTP_PASS=your-smtp-password

Set `SMTP_HOST` to enable SMTP. If both `SMTP_HOST` and `RESEND_API_KEY` are present, SMTP takes priority. If neither is set, emails are logged to the console (useful for development). In case of using Resend, the sender email must be verified in your Resend account.

If `SMTP_HOST` is set and an SMTP send attempt fails, the system will **not** automatically fall back to `RESEND_API_KEY` — the email will be silently dropped. To use Resend instead, unset `SMTP_HOST`.

[OAuth & Integrations](https://openpanel.dev/docs/self-hosting/environment-variables#oauth--integrations)

----------------------------------------------------------------------------------------------------------

### [SLACK\_CLIENT\_ID](https://openpanel.dev/docs/self-hosting/environment-variables#slack_client_id)

**Type**: `string`  
**Required**: No  
**Default**: None

Slack OAuth client ID for Slack integration.

**Example**:

    SLACK_CLIENT_ID=1234567890.1234567890

### [SLACK\_CLIENT\_SECRET](https://openpanel.dev/docs/self-hosting/environment-variables#slack_client_secret)

**Type**: `string`  
**Required**: No  
**Default**: None

Slack OAuth client secret for Slack integration.

**Example**:

    SLACK_CLIENT_SECRET=your-slack-client-secret

### [SLACK\_OAUTH\_REDIRECT\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#slack_oauth_redirect_url)

**Type**: `string`  
**Required**: No  
**Default**: None

Slack OAuth redirect URL. Must match the redirect URI configured in your Slack app.

**Example**:

    SLACK_OAUTH_REDIRECT_URL=https://analytics.example.com/api/integrations/slack/callback

### [SLACK\_STATE\_SECRET](https://openpanel.dev/docs/self-hosting/environment-variables#slack_state_secret)

**Type**: `string`  
**Required**: No  
**Default**: None

Secret for signing Slack OAuth state parameter.

**Example**:

    SLACK_STATE_SECRET=your-state-secret

[Self-hosting](https://openpanel.dev/docs/self-hosting/environment-variables#self-hosting)

-------------------------------------------------------------------------------------------

### [SELF\_HOSTED](https://openpanel.dev/docs/self-hosting/environment-variables#self_hosted)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Enable self-hosted mode. Set to `true` or `1` to enable self-hosting features. Used by both the dashboard frontend and API service.

**Example**:

    SELF_HOSTED=true

[Worker & Queue](https://openpanel.dev/docs/self-hosting/environment-variables#worker--queue)

----------------------------------------------------------------------------------------------

### [WORKER\_PORT](https://openpanel.dev/docs/self-hosting/environment-variables#worker_port)

**Type**: `number`  
**Required**: No  
**Default**: `3000`

Port for the worker service to listen on.

**Example**:

    WORKER_PORT=3000

### [DISABLE\_BULLBOARD](https://openpanel.dev/docs/self-hosting/environment-variables#disable_bullboard)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Disable BullMQ board UI. Set to `true` or `1` to disable the queue monitoring dashboard.

**Example**:

    DISABLE_BULLBOARD=true

### [DISABLE\_WORKERS](https://openpanel.dev/docs/self-hosting/environment-variables#disable_workers)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Disable all worker processes. Set to `true` or `1` to disable background job processing.

**Example**:

    DISABLE_WORKERS=true

### [ENABLED\_QUEUES](https://openpanel.dev/docs/self-hosting/environment-variables#enabled_queues)

**Type**: `string` (comma-separated)  
**Required**: No  
**Default**: All queues enabled

Comma-separated list of queue names to enable. Available queues: `events`, `events_kafka`, `sessions`, `cron`, `notification`, `misc`, `import`.

**Example**:

    ENABLED_QUEUES=events,sessions,cron

Enable `events_kafka` to run the Kafka-based events consumer alongside (or instead of) the default `events` queue. See the [Event Streaming (Kafka)](https://openpanel.dev/docs/self-hosting/environment-variables#event-streaming-kafka)
 section for the full configuration. A common high-throughput layout is to run one worker pool with `ENABLED_QUEUES=events_kafka` and another pool with everything else.

### [EVENT\_JOB\_CONCURRENCY](https://openpanel.dev/docs/self-hosting/environment-variables#event_job_concurrency)

**Type**: `number`  
**Required**: No  
**Default**: `10`

Number of concurrent event processing jobs per worker.

**Example**:

    EVENT_JOB_CONCURRENCY=20

### [EVENT\_BLOCKING\_TIMEOUT\_SEC](https://openpanel.dev/docs/self-hosting/environment-variables#event_blocking_timeout_sec)

**Type**: `number`  
**Required**: No  
**Default**: `1`

Blocking timeout in seconds for event queue workers.

**Example**:

    EVENT_BLOCKING_TIMEOUT_SEC=2

### [EVENTS\_GROUP\_QUEUES\_SHARDS](https://openpanel.dev/docs/self-hosting/environment-variables#events_group_queues_shards)

**Type**: `number`  
**Required**: No  
**Default**: `1`

Number of shards for the events group queue. Increase for better performance with high event volume.

**Example**:

    EVENTS_GROUP_QUEUES_SHARDS=4

### [QUEUE\_CLUSTER](https://openpanel.dev/docs/self-hosting/environment-variables#queue_cluster)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Enable Redis cluster mode for queues. When enabled, queue names are wrapped with `{}` for Redis cluster sharding.

**Example**:

    QUEUE_CLUSTER=true

### [ORDERING\_DELAY\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#ordering_delay_ms)

**Type**: `number`  
**Required**: No  
**Default**: `100`

Delay in milliseconds to hold events for correct ordering when events arrive out of order.

**Example**:

    ORDERING_DELAY_MS=200

Should not exceed 500ms. Higher values may cause delays in event processing.

### [AUTO\_BATCH\_MAX\_WAIT\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#auto_batch_max_wait_ms)

**Type**: `number`  
**Required**: No  
**Default**: `0` (disabled)

Maximum wait time in milliseconds for auto-batching events. Experimental feature.

**Example**:

    AUTO_BATCH_MAX_WAIT_MS=100

⚠️ **Experimental**: This feature is experimental and not used in production. Do not use unless you have a good understanding of the implications and specific performance requirements.

### [AUTO\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#auto_batch_size)

**Type**: `number`  
**Required**: No  
**Default**: `0` (disabled)

Batch size for auto-batching events. Experimental feature.

**Example**:

    AUTO_BATCH_SIZE=100

⚠️ **Experimental**: This feature is experimental and not used in production. Do not use unless you have a good understanding of the implications and specific performance requirements.

[Event Streaming (Kafka)](https://openpanel.dev/docs/self-hosting/environment-variables#event-streaming-kafka)

---------------------------------------------------------------------------------------------------------------

OpenPanel can optionally ingest events through a Kafka-compatible broker (Kafka itself, Redpanda, etc.) instead of (or alongside) the default Redis-backed events queue. This is opt-in per project and useful at high throughput, where many consumer instances can process partitions in parallel.

Routing is decided per event at produce time: if the project's ID matches `KAFKA_PROJECT_IDS` and `KAFKA_BROKERS` is set, the event is produced to the Kafka topic; otherwise it stays on the default Redis-backed `events` queue. Set `ENABLED_QUEUES=events_kafka` on the worker(s) that should consume from Kafka.

The client speaks the Kafka wire protocol via [kafkajs](https://kafka.js.org/)
, so any Kafka-compatible broker works. The bundled `docker-compose.yml` uses [Redpanda](https://redpanda.com/)
 as a lightweight, single-binary option, but you can point `KAFKA_BROKERS` at any Kafka cluster.

### [KAFKA\_BROKERS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_brokers)

**Type**: `string` (comma-separated) **Required**: Yes (to enable the Kafka path) **Default**: None

Comma-separated list of Kafka broker addresses. When unset, the Kafka producer/consumer is disabled and all events fall back to the default Redis-backed queue.

**Example**:

    KAFKA_BROKERS=redpanda:9092
    # Multiple brokers
    KAFKA_BROKERS=kafka-1:9092,kafka-2:9092,kafka-3:9092

### [KAFKA\_PROJECT\_IDS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_project_ids)

**Type**: `string` (comma-separated or `*`) **Required**: No **Default**: None (no projects route to Kafka)

Allow-list of project IDs whose events should be produced to Kafka. Use `*` to route every project's events through Kafka. If unset, no project uses Kafka even when `KAFKA_BROKERS` is configured.

**Example**:

    # Route every project through Kafka
    KAFKA_PROJECT_IDS=*
    
    # Route only specific projects
    KAFKA_PROJECT_IDS=proj_abc123,proj_def456

### [KAFKA\_EVENTS\_TOPIC](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_events_topic)

**Type**: `string` **Required**: No **Default**: `events`

Name of the Kafka topic used for incoming events.

**Example**:

    KAFKA_EVENTS_TOPIC=openpanel-events

### [KAFKA\_CONSUMER\_GROUP](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_consumer_group)

**Type**: `string` **Required**: No **Default**: `openpanel-events`

Kafka consumer group ID used by the worker. All worker replicas with the same group ID share partition assignments cooperatively.

**Example**:

    KAFKA_CONSUMER_GROUP=openpanel-events

### [KAFKA\_CLIENT\_ID](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_client_id)

**Type**: `string` **Required**: No **Default**: `openpanel`

Kafka client ID used by both producer and consumer. Shows up in broker logs and metrics.

**Example**:

    KAFKA_CLIENT_ID=openpanel-prod

### [KAFKA\_PARTITIONS\_CONCURRENT](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_partitions_concurrent)

**Type**: `number` **Required**: No **Default**: `8`

Maximum number of partitions a single consumer instance processes concurrently. Has no effect beyond the number of partitions actually assigned to this consumer.

**Example**:

    KAFKA_PARTITIONS_CONCURRENT=12

### [KAFKA\_MIN\_MESSAGES](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_min_messages)

**Type**: `number` **Required**: No **Default**: `1`

Minimum number of messages the broker should accumulate before responding to a fetch request (each message is assumed to be ~1 KiB internally). Higher values create larger batches at the cost of slightly higher latency.

**Example**:

    KAFKA_MIN_MESSAGES=16

### [KAFKA\_MAX\_WAIT\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_max_wait_ms)

**Type**: `number` **Required**: No **Default**: `500`

Maximum time in milliseconds the broker waits to fulfil `KAFKA_MIN_MESSAGES` before returning a fetch response. Caps end-to-end latency under low traffic.

**Example**:

    KAFKA_MAX_WAIT_MS=200

### [KAFKA\_MAX\_MESSAGES\_PER\_PARTITION](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_max_messages_per_partition)

**Type**: `number` **Required**: No **Default**: `256`

Maximum number of messages returned per partition per fetch request (each message is assumed to be ~1 KiB internally). Caps in-memory batch size during backlog recovery and bounds the worst-case time the consumer spends on a single batch.

**Example**:

    KAFKA_MAX_MESSAGES_PER_PARTITION=512

### [KAFKA\_SESSION\_TIMEOUT\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_session_timeout_ms)

**Type**: `number` **Required**: No **Default**: `30000`

Consumer group session timeout in milliseconds. The broker considers a consumer dead and rebalances its partitions if it does not heartbeat within this window.

**Example**:

    KAFKA_SESSION_TIMEOUT_MS=45000

### [KAFKA\_HEARTBEAT\_INTERVAL\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_heartbeat_interval_ms)

**Type**: `number` **Required**: No **Default**: `3000`

How often, in milliseconds, the consumer sends background heartbeats to the broker. Should be well below `KAFKA_SESSION_TIMEOUT_MS`.

**Example**:

    KAFKA_HEARTBEAT_INTERVAL_MS=3000

[Buffers](https://openpanel.dev/docs/self-hosting/environment-variables#buffers)

---------------------------------------------------------------------------------

### [SESSION\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#session_buffer_batch_size)

**Type**: `number`  
**Required**: No  
**Default**: Buffer-specific default

Batch size for session buffer operations.

**Example**:

    SESSION_BUFFER_BATCH_SIZE=5000

### [SESSION\_BUFFER\_CHUNK\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#session_buffer_chunk_size)

**Type**: `number`  
**Required**: No  
**Default**: Buffer-specific default

Chunk size for session buffer operations.

**Example**:

    SESSION_BUFFER_CHUNK_SIZE=1000

### [EVENT\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#event_buffer_batch_size)

**Type**: `number`  
**Required**: No  
**Default**: `4000`

Batch size for event buffer operations.

**Example**:

    EVENT_BUFFER_BATCH_SIZE=5000

### [EVENT\_BUFFER\_CHUNK\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#event_buffer_chunk_size)

**Type**: `number`  
**Required**: No  
**Default**: `1000`

Chunk size for event buffer operations.

**Example**:

    EVENT_BUFFER_CHUNK_SIZE=2000

### [PROFILE\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#profile_buffer_batch_size)

**Type**: `number`  
**Required**: No  
**Default**: Buffer-specific default

Batch size for profile buffer operations.

**Example**:

    PROFILE_BUFFER_BATCH_SIZE=5000

### [PROFILE\_BUFFER\_CHUNK\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#profile_buffer_chunk_size)

**Type**: `number`  
**Required**: No  
**Default**: Buffer-specific default

Chunk size for profile buffer operations.

**Example**:

    PROFILE_BUFFER_CHUNK_SIZE=1000

### [PROFILE\_BUFFER\_TTL\_IN\_SECONDS](https://openpanel.dev/docs/self-hosting/environment-variables#profile_buffer_ttl_in_seconds)

**Type**: `number`  
**Required**: No  
**Default**: Buffer-specific default

Time-to-live in seconds for profile buffer entries.

**Example**:

    PROFILE_BUFFER_TTL_IN_SECONDS=3600

### [BOT\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#bot_buffer_batch_size)

**Type**: `number`  
**Required**: No  
**Default**: Buffer-specific default

Batch size for bot detection buffer operations.

**Example**:

    BOT_BUFFER_BATCH_SIZE=1000

[Performance & Tuning](https://openpanel.dev/docs/self-hosting/environment-variables#performance--tuning)

----------------------------------------------------------------------------------------------------------

### [IMPORT\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#import_batch_size)

**Type**: `number`  
**Required**: No  
**Default**: `5000`

Batch size for data import operations.

**Example**:

    IMPORT_BATCH_SIZE=10000

### [IP\_HEADER\_ORDER](https://openpanel.dev/docs/self-hosting/environment-variables#ip_header_order)

**Type**: `string` (comma-separated)  
**Required**: No  
**Default**: See [default order](https://github.com/Openpanel-dev/openpanel/blob/main/packages/common/server/get-client-ip.ts)

Custom order of HTTP headers to check for client IP address. Useful when behind specific proxies or CDNs.

**Example**:

    IP_HEADER_ORDER=cf-connecting-ip,x-real-ip,x-forwarded-for

The default order includes: `openpanel-client-ip`, `cf-connecting-ip`, `true-client-ip`, `x-client-ip`, `x-forwarded-for`, `x-real-ip`, and others. See the [source code](https://github.com/Openpanel-dev/openpanel/blob/main/packages/common/server/get-client-ip.ts)
 for the complete default list.

### [SHUTDOWN\_GRACE\_PERIOD\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#shutdown_grace_period_ms)

**Type**: `number`  
**Required**: No  
**Default**: `5000`

Grace period in milliseconds for graceful shutdown of services.

**Example**:

    SHUTDOWN_GRACE_PERIOD_MS=10000

### [API\_PORT](https://openpanel.dev/docs/self-hosting/environment-variables#api_port)

**Type**: `number`  
**Required**: No  
**Default**: `3000`

Port for the API service to listen on.

**Example**:

    API_PORT=3000

### [API\_HOST](https://openpanel.dev/docs/self-hosting/environment-variables#api_host)

**Type**: `string`  
**Required**: No  
**Default**: `0.0.0.0` (production) / `localhost` (development)

Host address for the API service to bind to. Set to `::` to enable IPv6 support (useful for platforms like Railway that use IPv6 for internal networking).

**Example**:

    # Default IPv4 only
    API_HOST=0.0.0.0
    
    # IPv6 (dual-stack, accepts both IPv4 and IPv6)
    API_HOST=::

Use `API_HOST=::` when deploying on platforms like Railway where private networking requires IPv6. The `::` address enables dual-stack mode, accepting both IPv4 and IPv6 connections on most systems.

[Logging](https://openpanel.dev/docs/self-hosting/environment-variables#logging)

---------------------------------------------------------------------------------

### [LOG\_LEVEL](https://openpanel.dev/docs/self-hosting/environment-variables#log_level)

**Type**: `string`  
**Required**: No  
**Default**: `info`

Logging level. Options: `error`, `warn`, `info`, `debug`.

**Example**:

    LOG_LEVEL=debug

### [LOG\_SILENT](https://openpanel.dev/docs/self-hosting/environment-variables#log_silent)

**Type**: `boolean`  
**Required**: No  
**Default**: `false`

Disable all logging output. Set to `true` to silence logs.

**Example**:

    LOG_SILENT=true

### [LOG\_PREFIX](https://openpanel.dev/docs/self-hosting/environment-variables#log_prefix)

**Type**: `string`  
**Required**: No  
**Default**: None

Prefix for log messages. Useful for identifying logs from different services.

**Example**:

    LOG_PREFIX=api

### [HYPERDX\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#hyperdx_api_key)

**Type**: `string`  
**Required**: No  
**Default**: None

HyperDX API key for sending logs to HyperDX for monitoring and analysis.

**Example**:

    HYPERDX_API_KEY=your-hyperdx-api-key

[Geo](https://openpanel.dev/docs/self-hosting/environment-variables#geo)

-------------------------------------------------------------------------

### [MAXMIND\_LICENSE\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#maxmind_license_key)

**Type**: `string`  
**Required**: No  
**Default**: None

MaxMind GeoLite2 license key for downloading GeoIP databases.

**Example**:

    MAXMIND_LICENSE_KEY=your-maxmind-license-key

Get your license key from [MaxMind](https://www.maxmind.com/en/accounts/current/license-key)
. Required for downloading GeoIP databases.

[Quick Reference](https://openpanel.dev/docs/self-hosting/environment-variables#quick-reference)

-------------------------------------------------------------------------------------------------

### [Required Variables](https://openpanel.dev/docs/self-hosting/environment-variables#required-variables)

For a basic self-hosted installation, these variables are required:

*   `DATABASE_URL` - PostgreSQL connection
*   `REDIS_URL` - Redis connection
*   `CLICKHOUSE_URL` - ClickHouse connection
*   `API_URL` - API endpoint URL
*   `DASHBOARD_URL` - Dashboard URL
*   `COOKIE_SECRET` - Session encryption secret

### [Optional but Recommended](https://openpanel.dev/docs/self-hosting/environment-variables#optional-but-recommended)

*   `RESEND_API_KEY` or `SMTP_HOST` - For email features (pick one)
*   `EMAIL_SENDER` - Email sender address
*   `OPENAI_API_KEY` and/or `ANTHROPIC_API_KEY` - For the in-app AI chat assistant

### [See Also](https://openpanel.dev/docs/self-hosting/environment-variables#see-also)

*   [Deploy with Docker Compose](https://openpanel.dev/docs/self-hosting/deploy-docker-compose)
    
*   [Deploy with Coolify](https://openpanel.dev/docs/self-hosting/deploy-coolify)
    
*   [Deploy with Dokploy](https://openpanel.dev/docs/self-hosting/deploy-dokploy)
    
*   [Deploy on Kubernetes](https://openpanel.dev/docs/self-hosting/deploy-kubernetes)
    

[Reverse proxy setup\
\
Previous Page](https://openpanel.dev/docs/self-hosting/reverse-proxy)
[High volume setup\
\
Next Page](https://openpanel.dev/docs/self-hosting/high-volume)

### On this page

[Database & Storage](https://openpanel.dev/docs/self-hosting/environment-variables#database--storage)
[DATABASE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#database_url)
[DATABASE\_URL\_DIRECT](https://openpanel.dev/docs/self-hosting/environment-variables#database_url_direct)
[DATABASE\_URL\_REPLICA](https://openpanel.dev/docs/self-hosting/environment-variables#database_url_replica)
[REDIS\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#redis_url)
[CLICKHOUSE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_url)
[CLICKHOUSE\_CLUSTER](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_cluster)
[CLICKHOUSE\_SETTINGS](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_settings)
[CLICKHOUSE\_SETTINGS\_REMOVE\_CONVERT\_ANY\_JOIN](https://openpanel.dev/docs/self-hosting/environment-variables#clickhouse_settings_remove_convert_any_join)
[Application URLs](https://openpanel.dev/docs/self-hosting/environment-variables#application-urls)
[API\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#api_url)
[DASHBOARD\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#dashboard_url)
[API\_CORS\_ORIGINS](https://openpanel.dev/docs/self-hosting/environment-variables#api_cors_origins)
[Authentication & Security](https://openpanel.dev/docs/self-hosting/environment-variables#authentication--security)
[COOKIE\_SECRET](https://openpanel.dev/docs/self-hosting/environment-variables#cookie_secret)
[COOKIE\_TLDS](https://openpanel.dev/docs/self-hosting/environment-variables#cookie_tlds)
[CUSTOM\_COOKIE\_DOMAIN](https://openpanel.dev/docs/self-hosting/environment-variables#custom_cookie_domain)
[DEMO\_USER\_ID](https://openpanel.dev/docs/self-hosting/environment-variables#demo_user_id)
[ALLOW\_REGISTRATION](https://openpanel.dev/docs/self-hosting/environment-variables#allow_registration)
[ALLOW\_INVITATION](https://openpanel.dev/docs/self-hosting/environment-variables#allow_invitation)
[AI Features](https://openpanel.dev/docs/self-hosting/environment-variables#ai-features)
[OPENAI\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#openai_api_key)
[OPENAI\_BASE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#openai_base_url)
[OPENAI\_PROJECT](https://openpanel.dev/docs/self-hosting/environment-variables#openai_project)
[OPENAI\_ORGANIZATION](https://openpanel.dev/docs/self-hosting/environment-variables#openai_organization)
[ANTHROPIC\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_api_key)
[ANTHROPIC\_BASE\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_base_url)
[ANTHROPIC\_TOKEN](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_token)
[ANTHROPIC\_VERSION](https://openpanel.dev/docs/self-hosting/environment-variables#anthropic_version)
[Email](https://openpanel.dev/docs/self-hosting/environment-variables#email)
[RESEND\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#resend_api_key)
[EMAIL\_SENDER](https://openpanel.dev/docs/self-hosting/environment-variables#email_sender)
[SMTP\_HOST](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_host)
[SMTP\_PORT](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_port)
[SMTP\_SECURE](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_secure)
[SMTP\_USER](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_user)
[SMTP\_PASS](https://openpanel.dev/docs/self-hosting/environment-variables#smtp_pass)
[OAuth & Integrations](https://openpanel.dev/docs/self-hosting/environment-variables#oauth--integrations)
[SLACK\_CLIENT\_ID](https://openpanel.dev/docs/self-hosting/environment-variables#slack_client_id)
[SLACK\_CLIENT\_SECRET](https://openpanel.dev/docs/self-hosting/environment-variables#slack_client_secret)
[SLACK\_OAUTH\_REDIRECT\_URL](https://openpanel.dev/docs/self-hosting/environment-variables#slack_oauth_redirect_url)
[SLACK\_STATE\_SECRET](https://openpanel.dev/docs/self-hosting/environment-variables#slack_state_secret)
[Self-hosting](https://openpanel.dev/docs/self-hosting/environment-variables#self-hosting)
[SELF\_HOSTED](https://openpanel.dev/docs/self-hosting/environment-variables#self_hosted)
[Worker & Queue](https://openpanel.dev/docs/self-hosting/environment-variables#worker--queue)
[WORKER\_PORT](https://openpanel.dev/docs/self-hosting/environment-variables#worker_port)
[DISABLE\_BULLBOARD](https://openpanel.dev/docs/self-hosting/environment-variables#disable_bullboard)
[DISABLE\_WORKERS](https://openpanel.dev/docs/self-hosting/environment-variables#disable_workers)
[ENABLED\_QUEUES](https://openpanel.dev/docs/self-hosting/environment-variables#enabled_queues)
[EVENT\_JOB\_CONCURRENCY](https://openpanel.dev/docs/self-hosting/environment-variables#event_job_concurrency)
[EVENT\_BLOCKING\_TIMEOUT\_SEC](https://openpanel.dev/docs/self-hosting/environment-variables#event_blocking_timeout_sec)
[EVENTS\_GROUP\_QUEUES\_SHARDS](https://openpanel.dev/docs/self-hosting/environment-variables#events_group_queues_shards)
[QUEUE\_CLUSTER](https://openpanel.dev/docs/self-hosting/environment-variables#queue_cluster)
[ORDERING\_DELAY\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#ordering_delay_ms)
[AUTO\_BATCH\_MAX\_WAIT\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#auto_batch_max_wait_ms)
[AUTO\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#auto_batch_size)
[Event Streaming (Kafka)](https://openpanel.dev/docs/self-hosting/environment-variables#event-streaming-kafka)
[KAFKA\_BROKERS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_brokers)
[KAFKA\_PROJECT\_IDS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_project_ids)
[KAFKA\_EVENTS\_TOPIC](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_events_topic)
[KAFKA\_CONSUMER\_GROUP](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_consumer_group)
[KAFKA\_CLIENT\_ID](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_client_id)
[KAFKA\_PARTITIONS\_CONCURRENT](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_partitions_concurrent)
[KAFKA\_MIN\_MESSAGES](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_min_messages)
[KAFKA\_MAX\_WAIT\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_max_wait_ms)
[KAFKA\_MAX\_MESSAGES\_PER\_PARTITION](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_max_messages_per_partition)
[KAFKA\_SESSION\_TIMEOUT\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_session_timeout_ms)
[KAFKA\_HEARTBEAT\_INTERVAL\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#kafka_heartbeat_interval_ms)
[Buffers](https://openpanel.dev/docs/self-hosting/environment-variables#buffers)
[SESSION\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#session_buffer_batch_size)
[SESSION\_BUFFER\_CHUNK\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#session_buffer_chunk_size)
[EVENT\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#event_buffer_batch_size)
[EVENT\_BUFFER\_CHUNK\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#event_buffer_chunk_size)
[PROFILE\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#profile_buffer_batch_size)
[PROFILE\_BUFFER\_CHUNK\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#profile_buffer_chunk_size)
[PROFILE\_BUFFER\_TTL\_IN\_SECONDS](https://openpanel.dev/docs/self-hosting/environment-variables#profile_buffer_ttl_in_seconds)
[BOT\_BUFFER\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#bot_buffer_batch_size)
[Performance & Tuning](https://openpanel.dev/docs/self-hosting/environment-variables#performance--tuning)
[IMPORT\_BATCH\_SIZE](https://openpanel.dev/docs/self-hosting/environment-variables#import_batch_size)
[IP\_HEADER\_ORDER](https://openpanel.dev/docs/self-hosting/environment-variables#ip_header_order)
[SHUTDOWN\_GRACE\_PERIOD\_MS](https://openpanel.dev/docs/self-hosting/environment-variables#shutdown_grace_period_ms)
[API\_PORT](https://openpanel.dev/docs/self-hosting/environment-variables#api_port)
[API\_HOST](https://openpanel.dev/docs/self-hosting/environment-variables#api_host)
[Logging](https://openpanel.dev/docs/self-hosting/environment-variables#logging)
[LOG\_LEVEL](https://openpanel.dev/docs/self-hosting/environment-variables#log_level)
[LOG\_SILENT](https://openpanel.dev/docs/self-hosting/environment-variables#log_silent)
[LOG\_PREFIX](https://openpanel.dev/docs/self-hosting/environment-variables#log_prefix)
[HYPERDX\_API\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#hyperdx_api_key)
[Geo](https://openpanel.dev/docs/self-hosting/environment-variables#geo)
[MAXMIND\_LICENSE\_KEY](https://openpanel.dev/docs/self-hosting/environment-variables#maxmind_license_key)
[Quick Reference](https://openpanel.dev/docs/self-hosting/environment-variables#quick-reference)
[Required Variables](https://openpanel.dev/docs/self-hosting/environment-variables#required-variables)
[Optional but Recommended](https://openpanel.dev/docs/self-hosting/environment-variables#optional-but-recommended)
[See Also](https://openpanel.dev/docs/self-hosting/environment-variables#see-also)