Deploying Kuvasz

Introduction

Kuvasz is a lightweight, open source uptime and SSL certificate monitoring tool built with Kotlin and Micronaut. Designed for simplicity and reliability, Kuvasz continuously monitors your websites and services, alerting you when something goes wrong or when SSL certificates are about to expire.

The name Kuvasz comes from the Hungarian dog breed known for its loyalty and watchfulness, making it a fitting name for a monitoring tool that keeps a constant eye on your infrastructure. The application stores monitoring data in PostgreSQL and provides a REST API for integration with other tools.

Key features of Kuvasz:

• Uptime Monitoring: Check if your services are responding correctly
• SSL Certificate Monitoring: Track certificate expiration and issues
• Multiple Alert Channels: Email, Slack, PagerDuty, and Telegram notifications
• Custom Check Intervals: Configure monitoring frequency per endpoint
• Response Time Tracking: Monitor latency trends over time
• REST API: Full API for managing monitors and retrieving data
• Prometheus Metrics: Export metrics for Grafana dashboards
• Lightweight: Low resource footprint for efficient monitoring
• Database Storage: Historical data stored in PostgreSQL
• Open Source: MIT licensed and actively maintained

This guide walks through deploying Kuvasz on Klutch.sh using Docker, configuring monitoring checks, and setting up alerting.

Why Deploy Kuvasz on Klutch.sh

Deploying Kuvasz on Klutch.sh provides several advantages for uptime monitoring:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Kuvasz without complex orchestration.

Persistent Storage: Attach persistent volumes for historical monitoring data. Your metrics survive container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Always-On Monitoring: Critical for a monitoring tool that needs 24/7 availability.

Scalable Resources: Allocate CPU and memory based on the number of monitored endpoints.

Environment Variable Management: Securely store alerting credentials and database connections.

Custom Domains: Assign a custom domain for your monitoring dashboard.

Prerequisites

Before deploying Kuvasz on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• A PostgreSQL database for storing monitoring data
• (Optional) Slack, PagerDuty, or Telegram credentials for alerting
• (Optional) A custom domain for your Kuvasz instance

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for deploying Kuvasz on Klutch.sh.

Repository Structure

kuvasz-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM ghcr.io/kuvasz-uptime/kuvasz:latest

# Set environment variables
ENV MICRONAUT_SERVER_PORT=8080

# Expose the API port
EXPOSE 8080

# The base image includes the default entrypoint

Environment Variables Reference

Variable	Required	Default	Description
MICRONAUT_SERVER_PORT	No	8080	API server port
DATASOURCES_DEFAULT_URL	Yes	-	PostgreSQL JDBC URL
DATASOURCES_DEFAULT_USERNAME	Yes	-	Database username
DATASOURCES_DEFAULT_PASSWORD	Yes	-	Database password
HANDLER_SLACK_ENABLED	No	false	Enable Slack notifications
HANDLER_SLACK_WEBHOOK_URL	No	-	Slack webhook URL
HANDLER_PAGERDUTY_ENABLED	No	false	Enable PagerDuty notifications
HANDLER_PAGERDUTY_INTEGRATION_KEY	No	-	PagerDuty integration key
HANDLER_TELEGRAM_ENABLED	No	false	Enable Telegram notifications
HANDLER_TELEGRAM_API_TOKEN	No	-	Telegram bot token
HANDLER_TELEGRAM_CHAT_ID	No	-	Telegram chat ID
HANDLER_SMTP_ENABLED	No	false	Enable email notifications
HANDLER_SMTP_FROM	No	-	From email address
HANDLER_SMTP_TO	No	-	To email address

Deploying Kuvasz on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Kuvasz deployment configuration"
git remote add origin https://github.com/yourusername/kuvasz-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “kuvasz” or “uptime-monitor”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Kuvasz Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

Add the following environment variables:

Variable	Value
DATASOURCES_DEFAULT_URL	jdbc:postgresql://host:5432/kuvasz
DATASOURCES_DEFAULT_USERNAME	Your database user
DATASOURCES_DEFAULT_PASSWORD	Your database password
HANDLER_SLACK_ENABLED	true (if using Slack)
HANDLER_SLACK_WEBHOOK_URL	Your Slack webhook URL

Attach Persistent Volumes

Kuvasz uses PostgreSQL for data storage, so volumes are mainly for logs:

Mount Path	Recommended Size	Purpose
/app/logs	2 GB	Application logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Start the Kuvasz container
• Provision an HTTPS certificate

Access Kuvasz

Once deployment completes, access your Kuvasz API at https://your-app-name.klutch.sh.

Configuring Monitors

Creating Uptime Monitors

Add a new uptime monitor via the API:

curl -X POST https://your-kuvasz-domain/monitors \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Website",
    "url": "https://example.com",
    "uptimeCheckInterval": 60,
    "enabled": true
  }'

Creating SSL Monitors

Monitor SSL certificate expiration:

curl -X POST https://your-kuvasz-domain/monitors \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Website SSL",
    "url": "https://example.com",
    "sslCheckEnabled": true,
    "enabled": true
  }'

Monitor Configuration Options

Field	Description
name	Display name for the monitor
url	URL to monitor
uptimeCheckInterval	Seconds between uptime checks
sslCheckEnabled	Enable SSL certificate monitoring
enabled	Whether the monitor is active

Setting Up Alerting

Slack Integration

1. Create a Slack webhook in your workspace
2. Set HANDLER_SLACK_ENABLED=true
3. Set HANDLER_SLACK_WEBHOOK_URL to your webhook

PagerDuty Integration

1. Create a PagerDuty integration
2. Set HANDLER_PAGERDUTY_ENABLED=true
3. Set HANDLER_PAGERDUTY_INTEGRATION_KEY

Telegram Integration

1. Create a Telegram bot with BotFather
2. Get your chat ID
3. Set HANDLER_TELEGRAM_ENABLED=true
4. Set HANDLER_TELEGRAM_API_TOKEN and HANDLER_TELEGRAM_CHAT_ID

Prometheus Integration

Kuvasz exposes Prometheus metrics at /prometheus. Add to your Prometheus config:

scrape_configs:
  - job_name: 'kuvasz'
    static_configs:
      - targets: ['your-kuvasz-domain:8080']

Troubleshooting Common Issues

Database Connection Errors

• Verify PostgreSQL JDBC URL format
• Check database credentials
• Ensure database is accessible from Klutch.sh

Alerts Not Sending

• Verify alert handler is enabled
• Check webhook URLs and credentials
• Review application logs for errors

Monitors Not Running

• Verify monitor is enabled
• Check for database connectivity
• Review logs for check failures

Additional Resources

• Kuvasz GitHub Repository
• Kuvasz Documentation

Conclusion

Deploying Kuvasz on Klutch.sh gives you a lightweight, reliable uptime and SSL monitoring solution with automatic builds and secure access. Keep watch over your infrastructure without the complexity of larger monitoring platforms.