Installation

Kuvasz is distributed as a Docker image, which makes it easy to deploy and run on any system that supports Docker. This guide will walk you through the installation process.

Prerequisites

Whatever your setup will be, you'll need two things to make Kuvasz work:

PostgreSQL

Kuvasz relies on a PostgreSQL database to store its data, but if you don't have one set up already, you can use the provided Docker compose file to easily set up a PostgreSQL instance alongside Kuvasz.

YAML configuration file

While you can run Kuvasz without a configuration file using a very minimal setup, it probably won't make much sense, because you won't be able to set up any integrations, for example. Fortunately, you just need a simple YAML file, which is mounted as a volume in the Docker container under /config/kuvasz.yml.

From now on we'll assume that you have a .yaml file somewhere on your machine where you would like to deploy Kuvasz. Watch out! You'll probably need to adjust the volume mapping in the example below.

For the sake of simplicity, you can start with an empty file and we'll go through the available configuration options later in the process, or you can take a look at the Configuration section of the documentation right now to see how you can set up integrations, app-level settings, or even your monitors there.

Quick start with Docker Compose

services:
  kuvasz-db:
    image: postgres:17-alpine
    container_name: kuvaszdb
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres # (1)!
      TZ: 'UTC' # (7)!
    ports:
      - "5432:5432"
    volumes:
      - /path/to/your/pgdata:/var/lib/postgresql/data # (2)!
  kuvasz:
    image: kuvaszmonitoring/kuvasz:latest
    container_name: kuvasz
    mem_limit: 384M # optional (3)
    ports:
      - "8080:8080"
    environment:
      TZ: 'UTC' # (8)!
      DATABASE_HOST: kuvaszdb # (4)!
      DATABASE_USER: postgres # (5)!
      DATABASE_PASSWORD: postgres # (9)!
      ADMIN_USER: YourSuperSecretUsername # change it
      ADMIN_PASSWORD: YourSuperSecretPassword # change it
      ADMIN_API_KEY: ThisShouldBeVeryVerySecureToo # change it
    volumes:
      - /path/to/your/kuvasz.yml:/config/kuvasz.yml # (6)!
    depends_on:
      - kuvasz-db

services:
  kuvasz:
    image: kuvaszmonitoring/kuvasz:latest
    container_name: kuvasz
    mem_limit: 384M # optional (1)
    ports:
      - "8080:8080"
    environment:
      TZ: 'UTC' # (2)!
      DATABASE_HOST: localhost # optional, default is `localhost`
      DATABASE_PORT: 5432 # optional, default is 5432
      DATABASE_NAME: postgres # optional, default is `postgres`
      DATABASE_USER: postgres # use your own
      DATABASE_PASSWORD: postgres # use your own
      ADMIN_USER: YourSuperSecretUsername # change it
      ADMIN_PASSWORD: YourSuperSecretPassword # change it
      ADMIN_API_KEY: ThisShouldBeVeryVerySecureToo # change it
    volumes:
      - /path/to/your/kuvasz.yml:/config/kuvasz.yml # (3)!

After a successful start

If you've done everything correctly, and you've started the specified Compose stack, you should be able to access the web UI of Kuvasz at http://0.0.0.0:8080 (or the port you specified).

If you didn't disable authentication, you should see the login page, where you can log in with the credentials you specified. Otherwise, you should be redirected to the dashboard of Kuvasz.

Setting up integrations (a.k.a "Notifications")

Setting up integrations is as simple as adding a few lines to your YAML configuration. You can find the available options in the Integrations setup section of the documentation.

Setting up Slack as a global notification channel for all of your monitors, for example, would look like this:

integrations:
  slack:
    - name: use_your_desired_name
      webhook-url: 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXX'
      global: true # (1)!

1. If you set global: true, this integration will be used for all monitors by default, even if they don't have a specific integration assigned to them.

Creating your first monitor

You have 3 options to manage your monitors:

• using the Web UI, which is probably the most user-friendly way
• using the REST API, which is more suitable for automation and integration with other systems
• using the YAML configuration, which is useful if you would like to handle all of your configurations as code

Other installation methods

If you use another container orchestration system (e.g. k8s, Swarm, etc.), you can still use the same image and the same configuration options, of course. Just make sure to set the environment variables and mount the configuration file as shown above.

Readiness/health probes

If you run Kuvasz in a container orchestration system, you can use the GET /api/v1/health endpoint as a readiness probe to check if the application is UP and running. The endpoint doesn't need authentication, and returns a simple JSON response with the status of the application.

{
  "status": "UP"
}

Upgrading from v1 to v2

If you're upgrading from Kuvasz v1 to Kuvasz v2, it's better if you just start with a fresh setup, except for the database (make sure that you do a backup of it), which should be backward compatible. Even if it's not a complete rewrite, a lot of things have changed under the hood, and the new version is not fully compatible with the old one.

All in all, you can use your old database, your data will be migrated automatically, but there are a few notable breaking changes you should be aware of:

• Kuvasz is not distributed as a native (GraalVM based) Docker image anymore
• The minimum required PostgreSQL version is now 12
• The REST API is versioned now, and a few endpoints have been changed or removed. You can find the new API documentation here
• Integrations are now configured via the YAML file, and the old, environment-variable-based configuration is no longer supported
• The authentication and its configuration has been simplified, read the Authentication section carefully!