Deployment
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 deployment process.
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. The Helm chart also provides a basic database setup, if you don't want to bring your own PostgreSQL instance (be aware that it might not be a good fit for a production setup).
The minimum, tested version of PostgreSQL is 14, alpine distributions are supported.
How much memory and CPU does Kuvasz need?
With the default settings, Kuvasz needs 768 MB of memory and 1 CPU for up to 1,000 monitors (less monitors would most probably fit well under 512 MB, but 768 MB is a safe limit here). If you have more monitors, see the hardware requirements.
Choose Your Deployment Method
Kuvasz can be deployed in several ways depending on your infrastructure:
- Interactive install script - The fastest way to get a secure Docker Compose setup on Linux or macOS
- Docker Compose - Recommended for quick start and simple deployments
- Helm Chart - Recommended for Kubernetes clusters
- Other Deployment Methods
- One-click Deployment Options
Interactive install script
If you're on Linux or macOS, and you have Docker & Docker Compose installed, the install script sets up the same Docker Compose stack as the manual guide below, but it asks for your credentials and settings first, so you don't have to edit any file by hand:
curl -fsSL https://raw.githubusercontent.com/kuvasz-uptime/kuvasz/refs/heads/main/docker-examples/install.sh | bash
Prefer to look into the script before running it?
After a summary of your answers, the script writes the docker-compose.yml & kuvasz.yml files, starts the stack, and prints the location of the files. They're regular files, just like the ones in the manual guide, so you can edit them later the same way (e.g. to set up your integrations), then restart the stack to apply the changes.
Info
The script never overwrites an existing Docker Compose file (it stops instead), and keeps your existing kuvasz.yml untouched. If the database volume of a previous installation in the same directory still exists, it warns you: PostgreSQL keeps the data, and the user & password the volume was created with, so you have to enter the same credentials again (or remove the volume first). On Windows, follow the manual guide below.
Quick start with Docker Compose
TL;DR - A very quick start
- Make sure you have Docker & Docker Compose installed.
-
Run the following commands in your terminal
mkdir kuvasz-uptime && cd kuvasz-uptime touch kuvasz.yml curl -L https://raw.githubusercontent.com/kuvasz-uptime/kuvasz/refs/heads/main/docker-examples/docker-compose.yml -o docker-compose.yml # At this point you might want to change your docker-compose.yml and/or your # kuvasz.yml files to change the default configuration, especially the # credentials and secrets in there docker compose up -dmkdir kuvasz-uptime; cd kuvasz-uptime New-Item kuvasz.yml -ItemType File Invoke-WebRequest -Uri "https://raw.githubusercontent.com/kuvasz-uptime/kuvasz/refs/heads/main/docker-examples/docker-compose.yml" -OutFile "docker-compose.yml" # At this point you might want to change your docker-compose.yml and/or your # kuvasz.yml files to change the default configuration, especially the # credentials and secrets in there docker compose up -d -
Go to
http://0.0.0.0:8080, provideYourSuperSecretUsernameandYourSuperSecretPasswordas credentials, click "Sign in". - Look around and make sure that you change the default values of secrets and credentials in the
docker-compose.ymlfile ASAP! Setting your timezone might be also necessary if you are not located in UTC. - Read the Configuration reference & the Integration setup guide.
1. Configuration file
Create a file called kuvasz.yml somewhere on your machine, where you will create your Docker Compose file too in the next step.
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.
2. Docker Compose file
Create a file called docker-compose.yml in the same directory where you created the kuvasz.yml file in the previous step, and add the following content to it. Please make sure to change the credentials (see the comments below) to secure ones!
services:
# You can omit this service if you already have a PostgreSQL instance running somewhere,
# but in this case make sure to adjust the connection details of the kuvasz service accordingly
kuvasz-db:
image: pgautoupgrade/pgautoupgrade:18-alpine
restart: unless-stopped
environment:
POSTGRES_USER: kuvasz
POSTGRES_PASSWORD: YourSuperSecretDbPassword # change it!
TZ: 'UTC' # optional, but recommended, use your own timezone
healthcheck:
test: [ "CMD", "pg_isready", "-U", "kuvasz" ]
interval: 10s
start_period: 30s
volumes:
- kuvasz-db-data:/var/lib/postgresql
kuvasz:
image: kuvaszmonitoring/kuvasz:latest
restart: unless-stopped
# If you plan to run Kuvasz on an ARM based system, you might need to uncomment this line, depending on your setup
# platform: linux/arm64
# Uncomment these lines to run Kuvasz as a non-root user (make sure that your config file is readable by it)
# See: https://kuvasz-uptime.dev/management/examples/#running-kuvasz-as-a-non-root-user
# user: "1000:1000"
# cap_drop:
# - ALL
# security_opt:
# - no-new-privileges:true
ports:
# If the port 8080 is already in use on your host machine, change the left side of the mapping (e.g. "9090:8080")
- "8080:8080"
environment:
TZ: 'UTC' # optional, but recommended, match it with the kuvasz-db service above
DATABASE_HOST: kuvasz-db # the service name of the PostgreSQL service above
DATABASE_USER: kuvasz # the same user as in the PostgreSQL service above
DATABASE_PASSWORD: YourSuperSecretDbPassword # the same password as in the PostgreSQL service above
ADMIN_USER: YourSuperSecretUsername # change it!
ADMIN_PASSWORD: YourSuperSecretPassword # change it!
volumes:
# Make sure your config file is readable and the mount path is correct (/config/kuvasz.yml)
- ./kuvasz.yml:/config/kuvasz.yml
# Only needed to monitor the containers of this machine through a Docker host with a "unix:///var/run/docker.sock" URL
# - /var/run/docker.sock:/var/run/docker.sock
# Only if you run Kuvasz as a non-root user AND mount the Docker socket above: the ID of the group owning the socket
# (look it up with `getent group docker | cut -d: -f3`, or use "0" on Docker Desktop)
# group_add:
# - "999"
healthcheck:
test: [ "CMD-SHELL", "wget --quiet --tries=1 --spider http://localhost:8080/api/v2/health || exit 1" ]
interval: 60s
start_period: 30s
depends_on:
kuvasz-db:
condition: service_healthy
volumes:
kuvasz-db-data:
Credential requirements & disabling authentication
In case you didn't set up an OIDC provider, you need to set your admin user and password:
ADMIN_PASSWORDmust be at least 12 characters and must not be equal toADMIN_USER.ADMIN_API_KEYis optional. If not provided, then API-key based authentication will be simply disabled. In case you provide one, it must be at least 16 characters.ADMIN_MCP_API_KEYis optional and only needed if you use the MCP server. It's a separate key fromADMIN_API_KEYand grants access to the/mcpendpoint only. In case you provide one, it must be at least 16 characters.
See the details in the Configuration.
If you would like to completely disable authentication, you should set the ENABLE_AUTH environment variable to false and then you can just simply omit every authentication related configuration.
Running as a non-root user
The image runs as root by default, but Kuvasz doesn't need any privileges, so you can run it as a non-root user as well, by uncommenting the related lines in the file above. Check out the related recipe for the details, and for a few things to keep in mind (e.g. file permissions, ICMP & Docker monitors).
3. Starting the stack
Run the following command in the same directory where you created all the files mentioned above:
If you've done everything correctly, you should be able to access the
web UI of Kuvasz at
http://0.0.0.0:8080 (or the port you specified).
Tip
If you run Kuvasz on a remote server, you should replace 0.0.0.0 with the server's IP address or your custom domain name.
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.
After a successful start
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)!
- 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.
Tip
If you modify your configuration (via YAML or ENV, it doesn't matter), you need to restart the Kuvasz container for the changes to take effect. In certain cases if you changed an environment variable, you might need to rebuild the container as well.
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
Keeping Kuvasz up-to-date
To update Kuvasz to the latest version, you just need to bump the version of your image and restart your container, if no other instructions were provided in the release notes. Furthermore, to make it easier to get notified about new releases, the UI will show a notification if a new version is available.
Not using the Web UI?
If you don't use the Web UI, you can also check for new releases on GitHub, or directly on the API of Kuvasz, under GET /api/v2/settings. You'll find the version related information in the response under the versionInfo key.
Readiness/health probes
If you run Kuvasz in a container orchestration system, you can use the GET /api/v2/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.
Tip
Besides the response body, the HTTP status code will also indicate the health of the application: non 2xx status codes indicate that the application is not healthy.
Other deployment methods
If you use another container orchestration system (e.g. Kubernetes without Helm, Docker Swarm, etc.), you can still use the same image and the same configuration options. Just make sure to set the environment variables and mount the configuration file as shown in the Docker Compose example above.
Unofficial guides
Warning
The guides linked below are created and maintained by community members and are not official documentation. They may contain opinions, inaccuracies, or outdated information. Use them at your own discretion.
For official information, please always refer to the project’s documentation or source code.
- How to install Kuvasz on your Synology NAS
- Install Kuvasz via Docker (French)
- Install Kuvasz on Debian 12 (Spanish)
One-click deployment options
Warning
The one-click deployment options linked below are provided by third-party services and are not official deployment methods. They may have limitations, costs, or specific requirements. Use them at your own discretion.
Cloudzy
Kuvasz is available as a one-click deployment on Cloudzy, which allows you to get started with Kuvasz in just a few minutes without worrying about the underlying infrastructure. You can choose from various server configurations and locations to best suit your needs.