Self-Hosted Requirements
Hardware and software requirements for running KubeWatch on your own infrastructure.
Before deploying the self-hosted KubeWatch stack, make sure your infrastructure meets the following requirements.
Hardware
| Resource | Minimum | Recommended (production) |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU |
| RAM | 4 GB | 8 GB |
| Disk | 20 GB | 100 GB |
| Network | 100 Mbps | 1 Gbps |
The minimum spec is suitable for small teams monitoring fewer than 100 containers with 7-day metric retention. For production environments with longer retention or more agents, the recommended spec applies.
Disk usage is dominated by the TimescaleDB metrics tables. Estimate approximately 1 GB per 10,000 container-metrics-days (one container running for one day with default 15-second collection = ~5,760 rows).
Software
| Software | Minimum version | Notes |
|---|---|---|
| Docker | 24.0 | Required for Docker Compose deployment |
| Docker Compose | v2.20 | docker compose (V2), not docker-compose (V1) |
| curl | Any recent | Used by the install script |
| bash | 4.0+ | Used by the install script |
Verify Docker and Compose versions
docker --version
# Docker version 27.3.1, build ...
docker compose version
# Docker Compose version v2.29.1
If docker compose version fails (not found), you have Docker Compose V1 (docker-compose). Upgrade to Docker Compose V2 before proceeding.
Operating system
Tested and supported:
- Ubuntu 22.04 LTS and 24.04 LTS
- Debian 12 (Bookworm)
- RHEL 9 / CentOS Stream 9 / AlmaLinux 9
- Amazon Linux 2023
Other Linux distributions may work but are not officially supported.
Windows and macOS are supported for local development/testing only, not for production deployments.
Network requirements
Inbound ports
| Port | Protocol | Required for |
|---|---|---|
| 80 | TCP | HTTP (redirected to 443 if TLS enabled) |
| 443 | TCP | HTTPS dashboard and API |
If you change the default ports during installation, adjust your firewall rules accordingly.
Outbound access
During installation and upgrades, the server needs outbound access to:
| Destination | Port | Purpose |
|---|---|---|
ghcr.io | 443 | Pull Docker images from GitHub Container Registry |
github.com | 443 | Clone the repository (install script) |
After initial installation, outbound internet access is not required unless you need to pull updated images during an upgrade.
Agent hosts
Agents need outbound access to your self-hosted gateway:
| Destination | Port | Purpose |
|---|---|---|
| Your gateway domain | 443 | Agent registration and metric pushes |
Database
KubeWatch bundles PostgreSQL and the TimescaleDB extension in its Docker Compose stack, you don't need to install or manage them separately.
If you prefer to use an external PostgreSQL instance:
- PostgreSQL 15 or 16
- TimescaleDB 2.11 or later extension installed and enabled
- A dedicated database and user for KubeWatch
External database configuration is documented in Configuration Reference.