Install with Docker Compose

Deploy the full KubeWatch stack on your own server with the installer.

The self-hosted installer downloads the KubeWatch Compose file, generates your secrets, writes a reverse-proxy config, and starts the full stack. Everything runs on your server, no data leaves your environment.

Prerequisites

You need Docker Engine and the Docker Compose plugin on the server:

Verify both are available:

docker --version
docker compose version

Ports 80 and 443 must be open for inbound traffic, and the server needs outbound access to ghcr.io to pull images during install.

Install

Run the installer as a user with Docker access (or with sudo).

Option A: one-line install

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

Option B: review the script first (recommended)

Download it, read it, make it executable, then run it:

curl -fsSL -O https://raw.githubusercontent.com/lloyd-theophilus/kubewatch-releases/main/install.sh
less install.sh          # review what it does
chmod +x install.sh
sudo ./install.sh

Use `sudo` if your user is not in the `docker` group. You can add your user with `sudo usermod -aG docker $USER` and re-login to avoid `sudo` next time.

What the installer asks

The installer first asks which mode to run:

Mode	What it does
1) Connect to KubeWatch Cloud (agent only)	Deploys just the lightweight agent on this host, pointed at the hosted KubeWatch SaaS. Use this if you already have a KubeWatch Cloud account and only want to monitor this machine. It does not install the platform.
2) Self-Hosted (run everything locally)	Installs the complete KubeWatch platform on this server. Choose this to self-host.

For mode 2 it then prompts for:

Prompt	Example	Notes
Domain or IP	`monitoring.company.com`	A real domain enables automatic HTTPS. A bare IP serves over HTTP.
Admin email	`[email protected]`	Used to create the first admin account

The installer writes everything to ~/kubewatch-erp/ (Compose file, generated .env, and Caddyfile), pulls the images, and starts all services. It generates a random admin password and prints it at the end, save it.

Verify the installation

cd ~/kubewatch-erp
docker compose ps

All services should show running (or Up). The stack includes the API gateway, the backend services (auth, ingestion, query, alerting, notifications, live-data, and more), the PostgreSQL and metrics databases, and the dashboard, all behind a Caddy reverse proxy.

One exception: the `kubewatch-erp-migrate-1` container will show `Exited (0)`, and during install you'll see it log `Exited` in the startup output. This is expected, **not an error**. It is a one-shot job that applies the database migrations once and then stops. Every other container stays running.

If a service is not running, check its logs:

docker compose logs <service-name>

Access the dashboard

Domain: open https://your-domain.com
Bare IP: open http://your-server-ip

Log in with the admin email and the password printed at the end of the install (also in ~/kubewatch-erp/.env as ADMIN_PASSWORD). Change it after first login.

Lost the admin password?

You have two options, in order of preference:

Look it up. The originally generated password is stored on the server in ~/kubewatch-erp/.env:
```
grep ADMIN_PASSWORD ~/kubewatch-erp/.env
```
This is the password created at install time. It won't reflect a password you later changed in the dashboard.
Reset it. If you changed the password (or want a fresh one), reset it directly from the server. This works without email/SMTP:
```
cd ~/kubewatch-erp
docker compose exec auth /auth reset-password [email protected] 'YourNewPassword'
```
If the auth container isn't currently running, use a one-off instead:
```
docker compose run --rm --no-deps auth reset-password [email protected] 'YourNewPassword'
```
The new password must be at least 8 characters. You can then log in with it immediately.

Anyone with shell access to the server can run the reset command, so treat host access as full administrative access to KubeWatch.

Create an API key for agents

The platform starts with no agents connected. To monitor a host or cluster, create an API key in the dashboard under Settings → API Keys, then deploy an agent with it (see Deploying agents). For self-hosted, point the agent at your own gateway.

Starting, stopping, and logs

cd ~/kubewatch-erp

docker compose down        # stop (data is preserved)
docker compose up -d       # start
docker compose restart gateway   # restart one service
docker compose logs -f     # follow all logs

Next steps

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