> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keephq.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration
## Background
Keep is highly configurable through environment variables. This allows you to customize various aspects of both the backend and frontend components without modifying the code. Environment variables can be set in your deployment environment, such as in your Kubernetes configuration, Docker Compose file, or directly on your host system.
## Backend Environment Variables
### General
General configuration variables control the core behavior of the Keep server.
These settings determine fundamental aspects such as the server's host, port,
and whether certain components like the scheduler and consumer are enabled.
| Env var | Purpose | Required | Default Value | Valid options |
| :-------------------------------------: | :---------------------------------------------------: | :------: | :----------------------------: | :--------------------------: |
| **KEEP\_HOST** | Specifies the host for the Keep server | No | "0.0.0.0" | Valid hostname or IP address |
| **PORT** | Specifies the port on which the backend server runs | No | 8080 | Any valid port number |
| **SCHEDULER** | Enables or disables the workflow scheduler | No | "true" | "true" or "false" |
| **CONSUMER** | Enables or disables the consumer | No | "true" | "true" or "false" |
| **KEEP\_VERSION** | Specifies the Keep version | No | "unknown" | Valid version string |
| **KEEP\_API\_URL** | Specifies the Keep API URL | No | Constructed from HOST and PORT | Valid URL |
| **KEEP\_STORE\_RAW\_ALERTS** | Enables storing of raw alerts | No | "false" | "true" or "false" |
| **TENANT\_CONFIGURATION\_RELOAD\_TIME** | Time in minutes to reload tenant configurations | No | 5 | Positive integer |
| **KEEP\_LIVE\_DEMO\_MODE** | Keep will simulate incoming alerts and other activity | No | "false" | "true" or "false" |
### Logging and Environment
Logging and environment configuration determines how Keep generates and
formats log output. These settings are crucial for debugging, monitoring, and
understanding the behavior of your Keep instance in different environments.
| Env var | Purpose | Required | Default Value | Valid options |
| :--------------------: | :-----------------------------------------------------: | :------: | :---------------: | :---------------------------------------------: |
| **LOG\_LEVEL** | Sets the logging level for the application | No | "INFO" | "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL" |
| **ENVIRONMENT** | Specifies the environment the application is running in | No | "production" | "development", "staging", "production" |
| **LOG\_FORMAT** | Specifies the log format | No | "open\_telemetry" | "open\_telemetry", "dev\_terminal" |
| **LOG\_AUTH\_PAYLOAD** | Enables logging of authentication payload | No | "false" | "true" or "false" |
### Database
Database configuration is crucial for Keep's data persistence. Keep supports
various database backends through SQLAlchemy, allowing flexibility in choosing
and configuring your preferred database system.
| Env var | Purpose | Required | Default Value | Valid options |
| :------------------------------: | :-----------------------------------------------: | :------: | :-------------------------------: | :--------------------------------: |
| **DATABASE\_CONNECTION\_STRING** | Specifies the database connection URL | Yes | None | Valid SQLAlchemy connection string |
| **DATABASE\_POOL\_SIZE** | Sets the database connection pool size | No | 5 | Positive integer |
| **DATABASE\_MAX\_OVERFLOW** | Sets the maximum overflow for the connection pool | No | 10 | Positive integer |
| **DATABASE\_ECHO** | Enables SQLAlchemy echo mode for debugging | No | False | Boolean (True/False) |
| **DB\_CONNECTION\_NAME** | Specifies the Cloud SQL connection name | No | "keephq-sandbox:us-central1:keep" | Valid Cloud SQL connection string |
| **DB\_NAME** | Specifies the Cloud SQL database name | No | "keepdb" | Valid Cloud SQL database name |
| **DB\_SERVICE\_ACCOUNT** | Service account for database impersonation | No | None | Valid service account email |
| **DB\_IP\_TYPE** | Specifies the Cloud SQL IP type | No | "public" | "public", "private" or "psc" |
| **SKIP\_DB\_CREATION** | Skips database creation and migrations | No | "false" | "true" or "false" |
### Resource Provisioning
Resource provisioning settings control how Keep sets up initial resources.
This configuration is particularly important for automating the setup process
and ensuring that necessary resources are available when Keep starts.
To elaborate on resource provisioning and its configuration, please see
[provisioning docs](/deployment/provision/overview).
| Env var | Purpose | Required | Default Value | Valid options |
| :----------------------: | :---------------------------------------: | :------: | :-----------: | :---------------: |
| **PROVISION\_RESOURCES** | Enables or disables resource provisioning | No | "true" | "true" or "false" |
### Authentication
Authentication configuration determines how Keep verifies user identities and
manages access control. These settings are essential for securing your Keep
instance and integrating with various authentication providers.
For specific authentication type configuration, please see [authentication
docs](/deployment/authentication/overview).
| Env var | Purpose | Required | Default Value | Valid options |
| :---------------------------------------: | :---------------------------------------------------------------: | :------: | :-----------: | :--------------------------------------------------------------------: |
| **AUTH\_TYPE** | Specifies the authentication type | No | "NOAUTH" | "AUTH0", "KEYCLOAK", "DB", "NOAUTH", "OAUTH2PROXY", "OKTA", "ONELOGIN" |
| **KEEP\_JWT\_SECRET** | Secret key for JWT token generation and validation (DB auth only) | Yes | None | Any strong secret string |
| **KEEP\_DEFAULT\_USERNAME** | Default username for the admin user (DB auth only) | No | "keep" | Any valid username string |
| **KEEP\_DEFAULT\_PASSWORD** | Default password for the admin user (DB auth only) | No | "keep" | Any strong password string |
| **KEEP\_FORCE\_RESET\_DEFAULT\_PASSWORD** | Forces reset of default user password | No | "false" | "true" or "false" |
| **KEEP\_DEFAULT\_API\_KEYS** | Comma-separated list of default API keys to provision | No | "" | Format: "name:role:secret,name:role:secret" |
### Service Mesh (Internal Alert Ingestion)
These settings allow trusted services within the same Kubernetes cluster to
POST alerts to Keep without requiring a Keep API key. This is intended for
service-to-service communication where network-level authentication (e.g.
Istio mTLS with AuthorizationPolicy) ensures only authorized callers can
reach Keep's alert ingestion endpoints.
| Env var | Purpose | Required | Default Value | Valid options |
| :-------------------------------------: | :----------------------------------------------------------------: | :------: | :-----------: | :---------------: |
| **KEEP\_ALLOW\_MESH\_ALERT\_INGESTION** | Allows unauthenticated POST requests to `/alerts/event*` endpoints | No | "false" | "true" or "false" |
When `KEEP_ALLOW_MESH_ALERT_INGESTION` is set to `"true"`, requests to `/alerts/event*` that do not carry an API key or bearer token are accepted and authenticated as an internal service with the `webhook` role.
Calling services can optionally set the `X-Service-Name` HTTP header to identify themselves in Keep's logs and audit trail:
```bash theme={null}
curl -X POST http://keep-backend:8080/alerts/event \
-H "Content-Type: application/json" \
-H "X-Service-Name: my-service" \
-d '[{"id":"alert-1","name":"Example Alert","severity":"info","status":"firing","source":["my-service"]}]'
```
The authenticated entity will have:
* **email**: `service:` (defaults to `service:unknown` if the header is not set)
* **role**: `webhook` (grants `write:alert` and `write:incident` scopes)
This feature bypasses API key authentication for the alert ingestion
endpoints. You **must** pair it with network-level access control (such as
Istio AuthorizationPolicy) to restrict which services can reach these
endpoints. Without network-level enforcement, any client that can reach
Keep's backend can POST alerts.
### Secrets Management
Secrets Management configuration specifies how Keep handles sensitive
information. This is crucial for securely storing and accessing confidential
data such as API keys and integrations credentials.
| Env var | Purpose | Required | Default Value | Valid options |
| :----------------------------: | :-------------------------------------------------------------------: | :------: | :-----------: | :---------------------------------: |
| **SECRET\_MANAGER\_TYPE** | Defines the type of secret manager to use | Yes | "FILE" | "FILE", "GCP", "K8S", "VAULT", "DB" |
| **SECRET\_MANAGER\_DIRECTORY** | Directory for storing secrets when using file-based secret management | No | "/state" | Any valid directory path |
### OpenTelemetry
OpenTelemetry configuration enables comprehensive observability for Keep.
These settings allow you to integrate Keep with various monitoring and tracing
systems, enhancing your ability to debug and optimize performance.
| Env var | Purpose | Required | Default Value | Valid options |
| :-----------------------------------------: | :--------------------------------------------: | :------: | :-----------: | :-----------------------: |
| **OTEL\_SERVICE\_NAME** | OpenTelemetry service name | No | "keep-api" | Valid service name string |
| **SERVICE\_NAME** | Alternative for OTEL\_SERVICE\_NAME | No | "keep-api" | Valid service name string |
| **OTEL\_EXPORTER\_OTLP\_ENDPOINT** | OpenTelemetry collector endpoint | No | None | Valid URL |
| **OTLP\_ENDPOINT** | Alternative for OTEL\_EXPORTER\_OTLP\_ENDPOINT | No | None | Valid URL |
| **OTEL\_EXPORTER\_OTLP\_TRACES\_ENDPOINT** | OpenTelemetry traces endpoint | No | None | Valid URL |
| **OTEL\_EXPORTER\_OTLP\_LOGS\_ENDPOINT** | OpenTelemetry logs endpoint | No | None | Valid URL |
| **OTEL\_EXPORTER\_OTLP\_METRICS\_ENDPOINT** | OpenTelemetry metrics endpoint | No | None | Valid URL |
| **CLOUD\_TRACE\_ENABLED** | Enables Google Cloud Trace exporter | No | "false" | "true" or "false" |
| **METRIC\_OTEL\_ENABLED** | Enables OpenTelemetry metrics | No | "" | "true" or "false" |
### WebSocket Server (Pusher/Soketi)
WebSocket server configuration controls real-time communication capabilities
in Keep. These settings are important for enabling features that require
instant updates and notifications.
| Env var | Purpose | Required | Default Value | Valid options |
| :---------------------: | :-------------------------------: | :-------------------: | :-----------: | :--------------------------: |
| **PUSHER\_DISABLED** | Disables Pusher integration | No | "false" | "true" or "false" |
| **PUSHER\_HOST** | Hostname of the Pusher server | No | None | Valid hostname or IP address |
| **PUSHER\_PORT** | Port of the Pusher server | No | None | Any valid port number |
| **PUSHER\_APP\_ID** | Pusher application ID | Yes (if using Pusher) | None | Valid Pusher App ID |
| **PUSHER\_APP\_KEY** | Pusher application key | Yes (if using Pusher) | None | Valid Pusher App Key |
| **PUSHER\_APP\_SECRET** | Pusher application secret | Yes (if using Pusher) | None | Valid Pusher App Secret |
| **PUSHER\_USE\_SSL** | Enables SSL for Pusher connection | No | False | Boolean (True/False) |
| **PUSHER\_CLUSTER** | Pusher cluster | No | None | Valid Pusher cluster name |
### OpenAI
OpenAI configuration is used for integrating with OpenAI services. These
settings are important if you're utilizing OpenAI capabilities within Keep for
tasks such as natural language processing or AI-assisted operations.
| Env var | Purpose | Required | Default Value | Valid options | Backend/Frontend |
| :----------------------------: | :------------------------------------------------: | :------: | :-----------------: | :----------------------------------------------------------------: | :--------------: |
| **OPENAI\_API\_KEY** | API key for OpenAI services | No | None | Valid OpenAI API key | Both |
| **OPENAI\_MODEL\_NAME** | Model name to use for OpenAI requests | No | "gpt-4o-2024-08-06" | Valid OpenAI model name (e.g., "gpt-4o", "gpt-4o-mini", ...) | Both |
| **OPEN\_AI\_ORGANIZATION\_ID** | Organization ID for OpenAI services | No | None | Valid OpenAI organization ID | Both |
| **OPENAI\_BASE\_URL** | Base URL for OpenAI API (useful for LiteLLM proxy) | No | None | Valid URL (e.g., "[http://localhost:4000](http://localhost:4000)") | Both |
For various different LLM based features, we also require to set these
environment variables for Keep's frontend too.
### Posthog
Posthog configuration controls Keep's integration with the Posthog analytics
platform. These settings are useful for tracking usage patterns and gathering
insights about how your Keep instance is being used.
| Env var | Purpose | Required | Default Value | Valid options |
| :-------------------: | :---------------------------: | :------: | :------------------------------------------------: | :-------------------: |
| **POSTHOG\_API\_KEY** | API key for PostHog analytics | No | "phc\_muk9qE3TfZsX3SZ9XxX52kCGJBclrjhkP9JxAQcm1PZ" | Valid PostHog API key |
| **POSTHOG\_DISABLED** | Disables PostHog integration | No | "false" | "true" or "false" |
### Sentry
Sentry configuration controls Keep's integration with Sentry for error
monitoring and reporting. These settings are important for maintaining the
stability and reliability of your Keep instance.
| Env var | Purpose | Required | Default Value | Valid options |
| :------------------: | :-------------------------: | :------: | :-----------: | :---------------: |
| **SENTRY\_DISABLED** | Disables Sentry integration | No | "false" | "true" or "false" |
### Ngrok
Ngrok configuration enables secure tunneling to your Keep instance. These
settings are particularly useful for development or when you need to expose
your local Keep instance to the internet securely.
| Env var | Purpose | Required | Default Value | Valid options |
| :--------------------: | :----------------------------: | :------: | :-----------: | :--------------------: |
| **USE\_NGROK** | Enables ngrok for tunneling | No | "false" | "true" or "false" |
| **NGROK\_AUTH\_TOKEN** | Authentication token for ngrok | No | None | Valid ngrok auth token |
| **NGROK\_DOMAIN** | Custom domain for ngrok | No | None | Valid domain name |
### Elasticsearch
Elasticsearch configuration controls Keep's integration with Elasticsearch for
advanced search capabilities. These settings are important if you're using
Elasticsearch to enhance Keep's search functionality and performance.
| Env var | Purpose | Required | Default Value | Valid options |
| :------------------------: | :-----------------------------------------: | :--------------------------: | :-----------: | :---------------------------: |
| **ELASTIC\_ENABLED** | Enables Elasticsearch integration | No | "false" | "true" or "false" |
| **ELASTIC\_API\_KEY** | API key for Elasticsearch | Yes (if using Elasticsearch) | None | Valid Elasticsearch API key |
| **ELASTIC\_HOSTS** | Comma-separated list of Elasticsearch hosts | Yes (if using Elasticsearch) | None | Valid Elasticsearch host URLs |
| **ELASTIC\_USER** | Username for Elasticsearch basic auth | No | None | Valid username |
| **ELASTIC\_PASSWORD** | Password for Elasticsearch basic auth | No | None | Valid password |
| **ELASTIC\_INDEX\_SUFFIX** | Suffix for Elasticsearch index names | Yes (for single tenant) | None | Any valid string |
### Redis
Redis configuration specifies the connection details for Keep's Redis
instance. Redis is used for various caching and queueing purposes, making
these settings important for optimizing Keep's performance and scalability.
| Env var | Purpose | Required | Default Value | Valid options |
| :-----------------: | :-------------------: | :------: | :-----------: | :--------------------------: |
| **REDIS** | Redis enabled | No | false | true or false |
| **REDIS\_HOST** | Redis server hostname | No | "localhost" | Valid hostname or IP address |
| **REDIS\_PORT** | Redis server port | No | 6379 | Valid port number |
| **REDIS\_USERNAME** | Redis username | No | None | Valid username string |
| **REDIS\_PASSWORD** | Redis password | No | None | Valid password string |
### Redis Sentinel
Redis sentinel configuration specifies the connection details for Keep's Redis sentinel
instance. Redis sentinel is used when you have a redis cluster and it acts as a broker.
| Env var | Purpose | Required | Default Value | Valid options |
| :--------------------------------: | :-------------------------: | :------: | :---------------: | :-----------------------------------------: |
| **REDIS** | Redis enabled | No | false | true or false |
| **REDIS\_SENTINEL\_HOSTS** | Redis sentinel server(s) | No | "localhost:26379" | "host1:port1,host2:port2" (comma-separated) |
| **REDIS\_SENTINEL\_SERVICE\_NAME** | Redis sentinel service name | No | "mymaster" | Valid service name string |
| **REDIS\_USERNAME** | Redis username | No | None | Valid username string |
| **REDIS\_PASSWORD** | Redis password | No | None | Valid password string |
### ARQ
ARQ (Asynchronous Task Queue) configuration controls Keep's background task
processing. These settings are crucial for managing how Keep handles
long-running or scheduled tasks, ensuring efficient resource utilization and
responsiveness.
| Env var | Purpose | Required | Default Value | Valid options |
| :----------------------------: | :-------------------------------------------------: | :------: | :-----------: | :------------------: |
| **ARQ\_BACKGROUND\_FUNCTIONS** | Comma-separated list of background functions to run | No | None | Valid function names |
| **ARQ\_KEEP\_RESULT** | Duration to keep job results (in seconds) | No | 3600 | Positive integer |
| **ARQ\_EXPIRES** | Default job expiration time (in seconds) | No | 3600 | Positive integer |
| **ARQ\_EXPIRES\_AI** | AI job expiration time (in seconds) | No | 3600000 | Positive integer |
### Rate Limiting
Rate limiting configuration controls how many requests can be made to Keep's
API endpoints within a specified time period. This helps prevent abuse and
ensures system stability.
| Env var | Purpose | Required | Default Value | Valid options |
| :--------------------------: | :-----------------------------------: | :------: | :-----------: | :-----------------------------------------------------------------------------------: |
| **KEEP\_USE\_LIMITER** | Enables or disables rate limiting | No | "false" | "true" or "false" |
| **KEEP\_LIMIT\_CONCURRENCY** | Sets the rate limit for API endpoints | No | "100/minute" | Format: "{number}/{interval}" where interval can be "second", "minute", "hour", "day" |
Currently, rate limiting is applied to the following endpoints:
* POST `/alerts/event` - Generic event ingestion endpoint
* POST `/alerts/{provider_type}` - Provider-specific event ingestion endpoints
These endpoints are rate-limited according to the `KEEP_LIMIT_CONCURRENCY` setting when `KEEP_USE_LIMITER` is enabled.
### Maintenance Windows
The strategy enables the ability to manage how the alerts are handled
in case of a match with the Maintenance Windows Rules.
| Env var | Purpose | Required | Default Value | Valid options |
| :-------------------------------: | :-----------------------------------------: | :------: | :-----------: | :--------------------------------------: |
| **MAINTENANCE\_WINDOW\_STRATEGY** | Choose the strategy | No | "default" | "default" or "recover\_previous\_status" |
| **WATCHER\_LAPSED\_TIME** | Time in seconds to execute the alert review | No | 60 | Valid positive integer |
## Frontend Environment Variables
Frontend configuration variables control the behavior and features of Keep's
user interface. These settings are crucial for customizing the frontend's
appearance, functionality, and integration with the backend services.
### General
| Env var | Purpose | Required | Default Value | Valid options |
| ------------------------------------- | ------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- | -------------------- |
| **API\_URL** | Specifies the URL of the Keep backend API | Yes | None | Valid URL |
| **AUTH\_SESSION\_TIMEOUT** | Specifies user session timeout in seconds. Default is 30 days. | No | 2592000 | Value in seconds |
| **KEEP\_HIDE\_SENSITIVE\_FIELDS** | Hides sensitive fields | No | None | "true", "false" |
| **HIDE\_NAVBAR\_CORRELATION** | Hides the correlation page from the navigation bar in the UI | No | None | "true" |
| **HIDE\_NAVBAR\_WORKFLOWS** | Hides the workflows page from the navigation bar in the UI | No | None | "true" |
| **HIDE\_NAVBAR\_SERVICE\_TOPOLOGY** | Hides the service topology page from the navigation bar in the UI | No | None | "true" |
| **HIDE\_NAVBAR\_MAPPING** | Hides the mapping page from the navigation bar in the UI | No | None | "true" |
| **HIDE\_NAVBAR\_EXTRACTION** | Hides the extraction page from the navigation bar in the UI | No | None | "true" |
| **HIDE\_NAVBAR\_MAINTENANCE\_WINDOW** | Hides the maintenance window page from the navigation bar in the UI | No | None | "true" |
| **HIDE\_NAVBAR\_AI\_PLUGINS** | Hides the AI plugins page from the navigation bar in the UI | No | None | "true" |
| **KEEP\_WF\_LIST\_EXTENDED\_INFO** | Use a list instead a button to show the complete execution list | No | "true" | "true", "false" |
| **ALERT\_SIDEBAR\_FIELDS** | Specifies a list of fields to show in the sidebar. | No | service,source,description,message,fingerprint,url,incidents,timeline,relatedServices | Valid list of fields |
### Authentication
Authentication configuration determines how Keep verifies user identities and
manages access control. These settings are essential for securing your Keep
instance and integrating with various authentication providers.
| Env var | Purpose | Required | Default Value | Valid options |
| :------------------: | :-------------------------------: | :------: | :-----------: | :--------------------------------------------------------------------: |
| **AUTH\_TYPE** | Specifies the authentication type | No | "NOAUTH" | "AUTH0", "KEYCLOAK", "DB", "NOAUTH", "OAUTH2PROXY", "OKTA", "ONELOGIN" |
| **NEXTAUTH\_URL** | URL for NextAuth authentication | Yes | None | Valid URL |
| **NEXTAUTH\_SECRET** | Secret key for NextAuth | Yes | None | Strong secret string |
### Posthog
| Env var | Purpose | Required | Default Value | Valid options |
| :---------------: | :------------------------------------: | :------: | :-----------: | :-------------------: |
| **POSTHOG\_KEY** | PostHog API key for frontend analytics | No | None | Valid PostHog API key |
| **POSTHOG\_HOST** | PostHog Host for frontend analytics | No | None | Valid PostHog Host |
### Pusher
Pusher configuration is essential for enabling real-time updates and
communication in Keep's frontend. These settings allow the frontend to
establish a WebSocket connection with the Pusher server, facilitating instant
updates and notifications.
| Env var | Purpose | Required | Default Value | Valid options |
| :------------------: | :---------------------------: | :---------------------: | :-----------: | :--------------------------: |
| **PUSHER\_DISABLED** | Disables Pusher integration | No | "false" | "true" or "false" |
| **PUSHER\_HOST** | Hostname of the Pusher server | No | "localhost" | Valid hostname or IP address |
| **PUSHER\_PORT** | Port of the Pusher server | No | 6001 | Valid port number |
| **PUSHER\_APP\_KEY** | Pusher application key | Yes (if Pusher enabled) | "keepappkey" | Valid Pusher App Key |
| **PUSHER\_CLUSTER** | Pusher cluster | No | None | Valid Pusher cluster name |