Install with Docker Compose

Deploy the full KubeWatch stack using the one-line installer.

The easiest way to run the full self-hosted KubeWatch stack is the one-line installer. It handles cloning the repository, generating secrets, and starting all services.

One-line install

Run this on your server as a user with Docker access (or as root):

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

The installer will prompt you interactively for:

Prompt	Default	Notes
Domain	`localhost`	Your server's domain name. Use `localhost` for local access only.
Admin email	None	Used to create the first admin account
HTTP port	`80`	Change if port 80 is already in use
HTTPS port	`443`	Change if port 443 is already in use
Enable TLS?	`y`	Requires a valid domain with DNS pointing to this server

The installer will:

Clone the repository to /opt/kubewatch
Generate cryptographically random secrets for JWT_SECRET, POSTGRES_PASSWORD, and ADMIN_PASSWORD
Write a .env file at /opt/kubewatch/.env
Pull all Docker images
Start all services with docker compose up -d
Print the admin credentials

Total time: 2-5 minutes depending on internet speed.

Manual install

If you prefer full control over the process:

# 1. Clone the repository
git clone https://github.com/lloyd-theophilus/monitoring.git /opt/kubewatch
cd /opt/kubewatch

# 2. Copy the example environment file
cp .env.example .env

# 3. Edit the .env file with your values
nano .env   # or vim, or any editor

# 4. Start all services
docker compose up -d

Refer to the Configuration Reference for a full list of variables you should set in .env.

Verify the installation

Check that all services are running:

cd /opt/kubewatch
docker compose ps

Expected output, all services should show running:

NAME              IMAGE                          STATUS
gateway           kubewatch/gateway:latest       running
auth              kubewatch/auth:latest          running
ingestion         kubewatch/ingestion:latest     running
query             kubewatch/query:latest         running
live-data         kubewatch/live-data:latest     running
integrations      kubewatch/integrations:latest  running
dashboard         kubewatch/dashboard:latest     running
postgres          timescale/timescaledb:latest   running
redis             redis:7-alpine                 running

If any service is not running, check its logs:

docker compose logs <service-name>

Access the dashboard

If you used localhost: open http://localhost or http://localhost:3000
If you configured a domain: open https://your-domain.com

Log in with the admin email and the password printed at the end of the install, or found in /opt/kubewatch/.env as ADMIN_PASSWORD.

Starting and stopping

# Stop all services (data is preserved)
cd /opt/kubewatch && docker compose down

# Start all services
cd /opt/kubewatch && docker compose up -d

# Restart a single service
cd /opt/kubewatch && docker compose restart gateway

Viewing logs

# All services
docker compose logs -f

# Single service
docker compose logs -f gateway

Next steps

Configuration Reference, environment variables
Upgrading, update to a new version
Backup & Restore, protect your data