Installation

Prerequisites

You'll need a Postgres instance to connect to. If trying the bot out using Docker Compose or Helm, there are options to run a database alongside the app.
Configure and deploy the application using one of the methods described below, or however you choose. (There's a Docker image available.)

Slack

Create a Slack app for this application. You can name it whatever you'd like.
Select from an app manifest and copy manifest.yaml out of this repository and paste it in to automatically configure the app and its required settings. Be sure to override any customizable settings like name, etc.
You'll need the app token, bot token, and user token. For more information on Slack tokens, see the documentation here.

Matrix

Register a Matrix user account for the bot on your homeserver.
Generate an access token for the bot account.
Create a room to serve as the incident digest room and invite the bot.

Database Migrations

Database migrations run automatically when the container starts. The application's entrypoint runs alembic upgrade head before starting the server, so no separate migration job or init container is required.

This applies to all deployment methods — Helm, Docker Compose, and any other setup using the official image.

Required Variables

These variables are required for all installation methods:

POSTGRES_HOST - the hostname of the database.
POSTGRES_DB - database name to use.
POSTGRES_USER - database user to use.
POSTGRES_PASSWORD - password for the user.
POSTGRES_PORT - the port to use when connecting to the database.

Required when PLATFORM=slack (default):

SLACK_APP_TOKEN - the app-level token for enabling websocket communication. Found under your Slack app's Basic Information tab in the App-Level Tokens section.
SLACK_BOT_TOKEN - the API token to be used by your bot once it is deployed to your workspace for bot-scoped permissions. Found under your Slack app's OAuth & Permissions tab.
SLACK_USER_TOKEN - the API token to be used by your bot for user-scoped permissions. Found under your Slack app's OAuth & Permissions tab.

Required when PLATFORM=matrix:

MATRIX_HOMESERVER - URL of your Matrix homeserver (e.g. https://matrix.example.com).
MATRIX_USER_ID - Full Matrix user ID for the bot (e.g. @incidentbot:example.com).
MATRIX_ACCESS_TOKEN - Access token for the bot account.
MATRIX_DIGEST_ROOM_ID - Room ID to use as the incident digest room.

Architecture Support

Images are published as multi-arch manifests covering linux/amd64 and linux/arm64. Your container runtime selects the correct variant automatically — no additional configuration is required.

If you previously set image.suffix in your Helm values, you can remove it.

Kubernetes

Helm

You can get started quickly by using the Helm chart:

helm repo add incidentbot https://docs.incidentbot.io/charts
helm repo update

Sensitive data should come from Kubernetes Secret objects.

Warning

Secrets management is outside of the scope of this application. Choose the solution that works best for you. Any solution that renders a Kubernetes Secret that contains the key/value data for your sensitive application information will work.

One method is to used something like sealed-secrets.

If using sealed-secrets, you could put your sensitive environment variables in a .env file and create the Secret using the following command:

kubectl create secret generic incidentbot-secret --from-env-file=.env --dry-run='client' -ojson --namespace incidentbot >incidentbot-secret.json &&
  kubeseal --controller-name sealed-secrets <incidentbot-secret.json >incidentbot-secret-sealed.json &&
  kubectl create -f incidentbot-secret-sealed.json

Contained with .env, you'd want to include the sensitive values for this application. For example:

SLACK_APP_TOKEN=xapp-1-...
SLACK_BOT_TOKEN=...
SLACK_USER_TOKEN=xoxp-...
# any integration secrets
# and so on...

This will create the required Secret in the Namespace incidentbot. You may need to create the Namespace if it doesn't exist.

Create a values.yaml file. We'll call this one incidentbot-values.yaml:

envFromSecret:
  enabled: true
  secretName: incidentbot-secret
service:
  enabled: true
ingress:
  enabled: true
  annotations:
    kubernetes.io/ingress.class: nginx
    cert-manager.io/cluster-issuer: letsencrypt-prod
  hosts:
    - host: incidentbot.mydomain.com
      paths:
        - path: /
          pathType: ImplementationSpecific
  tls:
    - secretName: incidentbot-tls
      hosts:
        - incidentbot.mydomain.com

Run the following command to install the resources using the chart:

VERSION=$(helm search repo incidentbot --output=json | jq '.[0].version' | tr -d '"')
helm install incidentbot/incidentbot --version $VERSION --values incidentbot-values.yaml --namespace incidentbot

To clean everything up:

helm uninstall incidentbot --namespace incidentbot

Using the built-in database

There is an option for testing or demo environments to deploy a database alongside the application:

# values.yaml
database:
  enabled: true
  password: somepassword

Warning

This is not recommended for production use. You should setup a database independently and provide its credentials to the application instead.

Configuration

The application's config.yaml settings can be set using the configMap option:

# values.yaml
configMap:
  create: true
  data:
    options:
      skip_logs_for_user_agent:
        - kube-probe
        - ELB-HealthChecker/2.0
      timezone: America/New_York

Any data under the data key will be added to the ConfigMap and will be made available to the application.

You are not required to provide this option if you wish to use all of the default settings.

Consult the configuration page for details on all configurable options.

Docker Compose

A sample compose file is provided with sample variables. This is useful for running the application locally. In this scenario, the database runs as a container. This is not recommended for production usage.

Warning

Management of a database is outside of the scope of this application. Setup for a containerized database is provided for convenience when using Docker Compose.