Installing PodWarden | PodWarden Hub

One-Line Installer (Recommended)

curl -fsSL https://www.podwarden.com/install.sh | bash

The interactive installer checks prerequisites, asks for configuration, generates .env and docker-compose.yml, pulls pre-built images, and starts PodWarden. See Getting Started for details on what the installer asks.

Default install directory: /opt/podwarden/

Manual Installation

If you prefer to configure manually:

mkdir -p /opt/podwarden && cd /opt/podwarden

# Download the production compose file
curl -fsSL https://git.mediablade.net/podwarden/podwarden/-/raw/main/docker-compose.prod.yml \
  -o docker-compose.yml

# Create .env with your settings (see Configuration guide for all options)
cat > .env << 'EOF'
PW_POSTGRES_DB=podwarden
PW_POSTGRES_USER=podwarden
PW_POSTGRES_PASSWORD=<generate-a-strong-password>
PW_ENCRYPTION_KEY=<generate-with-openssl-rand-base64-32>
PW_API_PORT=8000
PW_UI_PORT=3000
NEXT_PUBLIC_PW_API_URL=http://<your-ip>:8000
FRONTEND_URL=http://<your-ip>:3000
EOF

# Pull and start
docker compose pull
docker compose up -d

Services:

podwarden-db — PostgreSQL 16 (internal only)
podwarden-api — FastAPI backend (port 8000, host networking)
podwarden-ui — Next.js frontend (port 3000)

Reverse Proxy (Optional)

PodWarden works fine accessed directly by IP and port on a LAN. For TLS or a custom domain, use Caddy, nginx, or Traefik:

podwarden.example.com {
    handle /api/* {
        reverse_proxy localhost:8000
    }
    handle {
        reverse_proxy localhost:3000
    }
}

Networking

The API container uses network_mode: host so it can directly reach target hosts via SSH for provisioning and kubectl. This means:

The API binds directly to the host's network interfaces (port 8000 by default)
The PostgreSQL container exposes its port to the host (port 5432 by default) so the API can reach it at 127.0.0.1:5432
Tailscale is optional — if all hosts are on the same LAN, the API can reach them by local IP or hostname

If you use Tailscale for host discovery, ensure the PodWarden server has Tailscale installed and authenticated.

Database

PostgreSQL data is stored in a Docker volume (pw-db-data). Migrations run automatically on startup from the migrations/ directory.

Backups

# Backup
docker exec pw-db pg_dump -U podwarden podwarden > backup.sql

# Restore
docker exec -i pw-db psql -U podwarden podwarden < backup.sql

Updating PodWarden

cd /opt/podwarden
docker compose pull
docker compose up -d

Migrations run automatically on API startup. Check logs after restart to verify all services are healthy:

docker compose logs -f