On-Prem Installation & Upgrade Guide

Prerequisites

• Docker 24+ with Compose plugin
• 10GB free disk space minimum
• Ports: 80, 443 (production with HTTPS) or 3000, 3001 (development)
• OS: Linux (recommended), macOS (development)

Fresh Installation

Step 1: Extract the Bundle

tar -xzf kafkaguard-onprem-v2.0.0.tar.gz
cd kafkaguard-onprem

Step 2: Run the Installer

./installer/install.sh

The installer will prompt you for:

Before running the installer, generate your machine fingerprint and send it to sales@kafkaguard.com to receive your license key:

./installer/fingerprint.sh

1. Host IP/hostname — the server address (default: localhost)
2. Admin email — your admin login email
3. Admin password — must be at least 12 characters
4. Organization name — your company name
5. License key — provided by KafkaGuard sales
6. TLS certificates — your own or auto-generated self-signed

Step 3: Verify Installation

# Check all services are running
docker compose -f docker-compose.onprem.yml ps

# Check API health
curl -k https://localhost/health

Open your browser to https://your-server and log in.

What Gets Created

Component	Description
PostgreSQL	Database (data in kafkaguard_postgres-data volume)
Redis	Job queue (data in kafkaguard_redis-data volume)
MinIO	Object storage for raw scans (data in kafkaguard_minio-data volume)
API	Fastify REST API on port 3001
Worker	BullMQ scan processor
Dashboard	Next.js UI on port 3000
Nginx	TLS termination, ports 80/443

Upgrading

Important: Your Data is Safe

Upgrades never touch your data. All data is stored in Docker named volumes:

• kafkaguard_postgres-data — database (clusters, scans, findings, users)
• kafkaguard_minio-data — raw scan JSON files
• kafkaguard_redis-data — job queue state

These volumes persist across container restarts and upgrades. Only the application containers (API, worker, dashboard) are replaced.

Note: If you migrate to a new server, you'll need a new license key. Run ./installer/fingerprint.sh on the new server and contact sales with the new fingerprint.

Upgrade Steps

# 1. Extract the new version alongside the existing one
tar -xzf kafkaguard-onprem-v1.1.0.tar.gz
cd kafkaguard-onprem

# 2. Run the upgrade script
./installer/upgrade.sh

The upgrade script automatically:

1. Creates a backup of your database and object storage
2. Verifies data volumes exist
3. Loads new Docker images from the bundle
4. Rolling restarts API, worker, dashboard, nginx (not database/redis/minio)
5. Runs database migrations at API startup
6. Waits for health check to confirm the API is ready

Verify After Upgrade

# Check version
curl -k https://localhost/health

# Check all data is intact
curl -k https://localhost/api/v1/clusters -H "Authorization: Bearer <your-token>"

Rollback

If something goes wrong, restore from the auto-backup:

# List available backups
./installer/backup.sh list

# Restore the pre-upgrade backup
./installer/backup.sh restore backups/kafkaguard-backup-YYYYMMDD-HHMMSS

Backup & Restore

Manual Backup

./installer/backup.sh backup

Creates a timestamped backup in ./backups/ containing:

• db.sql — full PostgreSQL dump
• minio-data/ — all scan files
• env.bak — environment configuration
• manifest.json — backup metadata

Restore

./installer/backup.sh restore backups/kafkaguard-backup-YYYYMMDD-HHMMSS

Scheduled Backups (Recommended)

Add to crontab for daily backups:

crontab -e
# Add this line for daily backup at 2 AM:
0 2 * * * /path/to/kafkaguard/installer/backup.sh backup /path/to/kafkaguard/backups

CLI Upgrade

The KafkaGuard CLI is a standalone binary — no data is stored locally. To upgrade:

Linux / macOS

# Download the latest release
curl -LO https://github.com/KafkaGuard/kafkaguard-releases/releases/latest/download/kafkaguard_$(uname -s)_$(uname -m).tar.gz

# Extract and replace
tar -xzf kafkaguard_*.tar.gz
sudo mv kafkaguard /usr/local/bin/kafkaguard

# Verify
kafkaguard version

Docker

docker pull kafkaguard/cli:latest

No Data Loss Risk

The CLI is stateless — it connects to Kafka, scans, and produces reports. Upgrading the binary has zero impact on:

• Your Kafka clusters
• Your On-Prem dashboard data
• Your scan history
• Your policies (YAML files you control)

Troubleshooting

Services won't start after upgrade

# Check logs
docker compose -f docker-compose.onprem.yml logs api --tail 50
docker compose -f docker-compose.onprem.yml logs worker --tail 50

# Check if migrations failed
docker compose -f docker-compose.onprem.yml logs api | grep -i "migration"

Database connection errors

# Verify postgres is healthy
docker compose -f docker-compose.onprem.yml exec postgres pg_isready -U kafkaguard

# Check volume exists
docker volume inspect kafkaguard_postgres-data

Rollback to previous version

# Restore from backup
./installer/backup.sh restore backups/<latest>

# Load old images if you still have the previous bundle
docker load -i /path/to/old-bundle/images/*.tar
docker compose -f docker-compose.onprem.yml up -d