Skip to main content

Server

First Install​

Dispatch uses the same configuration system as Starlette.

By default, the config is read from environment variables or .env files.

info

All config items prefixed with VITE_ are envvars for the Vue frontend. These variables are used only during the building of the javascript bundle. See here for details. You will want to include these variables in src/dispatch/static/dispatch/.env during build time.

info

In general, do not include any quotation marks when adding configuration values.

General​

LOG_LEVEL [default: 'WARNING']​

Controls the level of logging the application will perform during operations. Possible values: CRITICAL, ERROR, WARNING, INFO, DEBUG

STATIC_DIR [default: 'src/dispatch/static/dispatch/dist']​

Controls where on the local disk, static content for the Dispatch Web UI should be served. This variable can also be explicitly set to '' if you wish to serve static content outside of the Dispatch server.

METRIC_PROVIDERS [default: ""]​

A comma-separated list of metric providers where Dispatch will send key system metrics.

SECRET_PROVIDER [default: None]​

Defines the provider to use for configuration secret decryption. Available options are: kms-secret and metatron-secret

ENV_TAGS [default: ""]​

A comma-separated list of tags that Dispatch will attempt to pull from the environment. For example, the string foo:bar,baz:blah will create two tags: foo with the environment value for bar and baz with the environment value for blah.

SENTRY_DSN [default: none]​

Optional configuration for using Sentry to report Dispatch errors.

MJML_PATH [default: 'static/dispatch/node_modules/.bin' (relative to the package directory)]​

Dispatch uses MJML to generate its HTML emails. This package also requires the node binary to be available on the standard path (or set in Dispatch's path). Use this variable to adjust the location where Dispatch should look for the mjml command. If you are using the stock docker image of Dispatch you must manually set this field to the default path.

DISPATCH_UI_URL​

URL of the Dispatch's Admin UI, used by messaging to refer to the Admin UI.

Authentication​

DISPATCH_AUTHENTICATION_PROVIDER_SLUG ['default': dispatch-auth-provider-basic]​

Used by Dispatch to determine which authentication provider to use; by default, Dispatch ships with a basic authentication provider. A PKCE authentication provider (dispatch-auth-provider-pkce) is also available.

info

If you wish to disable authentication set DISPATCH_AUTHENTICATION_PROVIDER_SLUG=

Configuration for dispatch-auth-provider-basic​

warning

Today, basic authentication allows self-registration without approval.

info

For this plugin to work, you need to set DISPATCH_JWT_SECRET.

DISPATCH_JWT_SECRET​

Used by the basic auth provider to mint JWT tokens.

DISPATCH_JWT_ALG ['default': 'HS256']​

Used by the basic auth provider to mint JWT tokens.

DISPATCH_JWT_EXP ['default': 86400 ]​

Used by the basic auth provider to mint JWT tokens and set their expiration.

DISPATCH_JWT_AUDIENCE​

The aud the PKCE provider requires an id token to carry — normally the OIDC client id. Tokens issued for a different application are rejected. If your provider sets aud and this is unset, every token is rejected.

DISPATCH_JWT_EMAIL_OVERRIDE​

Override where Dispatch should find the user email in the idtoken. Defaults to the email claim. A token with no value for the configured claim is rejected.

DISPATCH_AUTHENTICATION_DEFAULT_USER ['default': dispatch@example.com]​

Used as the default anonymous user when authentication is disabled.

Configuration for dispatch-auth-provider-pkce​

This is Dispatch's generic OpenID Connect provider. It authenticates the browser with the authorization code flow plus PKCE, and validates the resulting token on every API request. It works with any spec-compliant OIDC provider — Okta, Google, Keycloak, Microsoft Entra ID. For a worked Entra example see Authenticating with Microsoft Entra ID.

info

For this plugin to work with your OIDC setup, you need to set DISPATCH_AUTHENTICATION_PROVIDER_PKCE_JWKS, DISPATCH_AUTHENTICATION_PROVIDER_PKCE_ISSUER and DISPATCH_JWT_AUDIENCE. You may additionally need DISPATCH_JWT_EMAIL_OVERRIDE and DISPATCH_PKCE_DONT_VERIFY_AT_HASH, depending on what your provider issues.

DISPATCH_AUTHENTICATION_PROVIDER_PKCE_JWKS​

Used by Dispatch's authentication backend to pull the JSON Web Key Set (JWKS) public key from the specified provider. This will likely be the jwks_uri URL from your OIDC provider. This is required when using the dispatch-auth-provider-pkce auth provider.

DISPATCH_AUTHENTICATION_PROVIDER_PKCE_ISSUER​

The exact iss value your provider mints, for example https://login.microsoftonline.com/<tenant-id>/v2.0. Tokens carrying any other issuer are rejected.

warning

Leaving this unset accepts any issuer whose signature the configured JWKS validates. Some providers — Microsoft Entra ID among them — sign every tenant's tokens with a shared key set, so without an expected issuer a valid signature does not establish which directory the user came from. Dispatch logs a warning at startup when the PKCE provider is selected and this is unset. It has no default so that existing deployments keep working, but a new deployment should always set it.

DISPATCH_AUTHENTICATION_PROVIDER_PKCE_JWKS_CACHE_SECONDS ['default': 300]​

How long the provider's signing keys are cached. Keys are also refetched immediately when a token arrives with a key id Dispatch has not seen, so a rotated signing key is picked up without waiting for this to expire.

DISPATCH_AUTHENTICATION_PROVIDER_PKCE_JWKS_TIMEOUT_SECONDS ['default': 5]​

Request timeout when fetching the JWKS. If the fetch fails and keys are already cached, the cached keys keep being used rather than failing every request for the duration of the provider's outage.

DISPATCH_AUTHENTICATION_PROVIDER_PKCE_LEEWAY_SECONDS ['default': 60]​

Clock skew tolerated when checking exp, nbf and iat. Set to 0 to require exact agreement with the identity provider's clock.

DISPATCH_PKCE_DONT_VERIFY_AT_HASH ['default': false]​

Depending on what values your OIDC provider sends, you may need to set this to true for the Dispatch backend to be able to decode the JWT token. Accepts true/false (or 1/0) only; any other value is rejected at startup.

info

Microsoft Entra ID emits at_hash only from its /authorize endpoint, never from the code-for-token exchange this flow uses, so an Entra deployment does not need this setting.

DISPATCH_AUTHENTICATION_PROVIDER_PKCE_OPEN_ID_CONNECT_URL​

The well-known configuration URL for your OIDC provider, without a trailing slash. Used by the Dispatch Web UI to authenticate a user via Proof Key Code Exchange (PKCE).

DISPATCH_AUTHENTICATION_PROVIDER_PKCE_CLIENT_ID​

The client id to send to the OpenID Connect endpoint.

DISPATCH_AUTHENTICATION_PROVIDER_USE_ID_TOKEN ['default': false]​

Use id_token instead of default access_token. Details Depends on the identity provider.

Configuration for dispatch-auth-provider-header​

Authenticate users based on HTTP request headers. Useful when Dispatch is behind a reverse proxy performing authentication.

DISPATCH_AUTHENTICATION_PROVIDER_HEADER_NAME ['default': remote-user]​

info

Make sure the reverse proxy strips this header from incoming requests (i.e. user-provided). Failure to do so will result in authentication bypass.

The HTTP request header to use as the user name, this value is case-insensitive.

Configuration for dispatch-auth-provider-aws-alb​

Authenticate users based on AWS Application Load Balancer authenticate.

DISPATCH_AUTHENTICATION_PROVIDER_AWS_ALB_ARN​

ARN of your Load Balancer, used to validate the signer. The format is arn:aws:elasticloadbalancing:region-code:account-id:loadbalancer/app/load-balancer-name/load-balancer-id. This is required when using the dispatch-auth-provider-aws-alb auth provider.

DISPATCH_AUTHENTICATION_PROVIDER_AWS_ALB_EMAIL_CLAIM ['default': email]​

Override where Dispatch should find the user email in the users claims.

DISPATCH_AUTHENTICATION_PROVIDER_AWS_ALB_PUBLIC_KEY_CACHE_SECONDS ['default': 300]​

Override how long Dispatch should cache the public key, used to validate the payload.

info

Add a ALB listener action without authenticate for /api/v1/{organization}/events/* if you want plugins to be public. Plugins determine their own authentication.

Persistence​

DATABASE_HOSTNAME​

Dispatch relies on a Postgres database. This hostname should point to a supported version of Postgres — this project tests against and deploys 18; there is no supported upgrade path from a pre-14 cluster.

DATABASE_CREDENTIALS [secret: True]​

Credentials specified in username:password format to be used to authenticate to the postgres database.

DATABASE_NAME [default: 'dispatch']​

Allows the user to specify the database name for the Dispatch backend.

DATABASE_PORT [default: '5432']​

Allows the user to specify the database port for the Dispatch backend.

Models​

Incident Cost​

Dispatch calculates the cost of an incident by adding up the time participants have spent on each incident role (e.g., Incident Commander) and applying an engagement multiplier that's based on the incident role. It also includes time spent on incident review-related activities. Dispatch calculates and publishes the cost for all incidents every 5 minutes.