Quickstart (Self-Hosted)

Run the full KubeWatch stack on your own infrastructure.

Self-hosted KubeWatch gives you the complete platform, gateway, auth, ingestion, query, live-data, and dashboard, running on your own servers. No data ever leaves your environment.

Prerequisites

Before you begin, make sure your server meets these requirements:

Requirement	Minimum	Recommended
CPU	2 vCPU	4 vCPU
RAM	4 GB	8 GB
Disk	20 GB	100 GB
Docker	24+	latest
Docker Compose	v2.20+	latest

Ports 80 and 443 must be open for inbound traffic. Outbound internet access is needed once during install to pull images from ghcr.io.

Supported operating systems: Ubuntu 22.04+, Debian 12+, RHEL 9+, Amazon Linux 2023.

Install with one command

Run the installer as a user with Docker access (or root):

curl -fsSL https://raw.githubusercontent.com/lloyd-theophilus/monitoring/main/install.sh | bash

The installer will prompt you for a few configuration values:

Prompt	Example	Notes
Domain	`kubewatch.example.com`	Use `localhost` for local-only access
Admin email	`admin@example.com`	Used for the first admin account
HTTP port	`80`	Change if 80 is taken
HTTPS port	`443`	Change if 443 is taken
Enable TLS?	`y`	Requires a valid domain with DNS pointing to this server

The installer clones the repository to /opt/kubewatch, generates a .env file with secrets, pulls all Docker images, and starts all services. This takes 2-5 minutes depending on your internet connection.

Verify the installation

Once the installer completes, check that all services are running:

cd /opt/kubewatch
docker compose ps

All services should show Up. You should see containers for: gateway, auth, ingestion, query, live-data, dashboard, postgres, and redis.

Access the dashboard

Open your browser and navigate to:

http://localhost (if you used localhost as your domain)
https://your-domain.com (if you configured a real domain with TLS)

Log in with the admin email you entered during setup. Your initial password was printed at the end of the install script, check your terminal output or /opt/kubewatch/.env for ADMIN_PASSWORD.

Deploy your first agent

With your self-hosted gateway running, deploy an agent on any host you want to monitor. Point it at your own gateway instead of the hosted KubeWatch cloud.

First, get your API key from Settings → API Keys in your self-hosted dashboard.

Then deploy the agent on the host you want to monitor:

docker run -d \
  --name kubewatch-agent \
  --restart unless-stopped \
  -e KUBEWATCH_API_KEY=YOUR_API_KEY \
  -e KUBEWATCH_SERVER_URL=https://your-domain.com \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/lloyd-theophilus/monitoring/kubewatch-agent:latest

Replace YOUR_API_KEY and https://your-domain.com with your actual values.

If your gateway uses a self-signed certificate, add `-e KUBEWATCH_TLS_SKIP_VERIFY=true` to the agent command. This is not recommended for production.

Next steps

Self-Hosted Requirements, full hardware and software details
Configuration Reference, all environment variables
Upgrading, how to update your installation
Backup & Restore, protect your data