Install Nebla
You need three things:
- A Proxmox VE 8 or 9 node or cluster.
- A Linux machine with Docker Compose that can reach the Proxmox API on port 8006. A small VM on the same host is enough.
- A URL for the panel, such as
https://panel.example.com.
1. Prepare Proxmox
Nebla talks to Proxmox only through its API. It never uses SSH and installs nothing on the host. Run these once per cluster, in a root shell on any node:
- Create the
Neblarole on/and theNeblaISOrole on your ISO storage. - Create the user
nebla@pveand give it both roles. - Create an API token with
pveum user token add nebla@pve panel --privsep 0, and keep the secret it prints. - Read the TLS fingerprint of the node you will connect to with
pvenode cert info.
The Proxmox setup guide has the exact privilege lists for PVE 8 and 9, the storage requirements, and the firewall setting that tenant isolation needs.
2. Start Nebla
Make a folder and save this as compose.yaml:
name: nebla
services:
panel:
image: ghcr.io/nebla-cloud/nebla:latest
restart: unless-stopped
stop_grace_period: 75s
depends_on:
postgres:
condition: service_healthy
ports:
- "${PANEL_PORT:-8080}:8080"
environment:
PANEL_DATABASE_URL: postgres://nebla:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}@postgres:5432/nebla?sslmode=disable
PANEL_LISTEN: ":8080"
PANEL_BASE_URL: ${PANEL_BASE_URL:?set PANEL_BASE_URL in .env}
PANEL_SECRET_KEY: ${PANEL_SECRET_KEY:?set PANEL_SECRET_KEY in .env}
PANEL_SMTP_URL: ${PANEL_SMTP_URL:-}
PANEL_TRUSTED_PROXIES: ${PANEL_TRUSTED_PROXIES:-}
healthcheck:
test: ["CMD", "/nebla-server", "healthcheck"]
interval: 15s
timeout: 5s
start_period: 20s
retries: 3
postgres:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_DB: nebla
POSTGRES_USER: nebla
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U nebla -d nebla"]
interval: 5s
timeout: 5s
retries: 10
volumes:
pgdata:
Next to it, create .env:
PANEL_BASE_URL=https://panel.example.com
PANEL_SECRET_KEY=
POSTGRES_PASSWORD=
PANEL_PORT=8080
Fill in the two secrets:
openssl rand -base64 48 # PANEL_SECRET_KEY
openssl rand -hex 24 # POSTGRES_PASSWORD
Keep PANEL_SECRET_KEY safe. Nebla uses it to seal the Proxmox token secrets it stores, and without it they can't be read.
Start it and check that it answers:
docker compose up -d
curl -fs localhost:8080/v1/healthz
Optional settings, such as SMTP for invite emails, trusted reverse proxies and default quotas, are listed in the configuration table.
3. Create the first admin account
Open the panel URL and create the first account. It becomes the panel admin. Later accounts come from the admin or from invite links. Open sign-up is off until you turn it on.
4. Connect your cluster
In the admin area:
- Add a location with the Proxmox URL, the token ID
nebla@pve!panel, its secret, the TLS fingerprint, and the disk and ISO storages. - Create server types, for example
small-2with 2 vCPU, 4 GB of memory and a 40 GB disk. - Add an IP pool with the bridge, optional VLAN tag, CIDR, gateway, DNS and the address range servers may use.
- Add images. On Proxmox VE 8.4 or later, enable official Debian, Ubuntu, Rocky Linux, AlmaLinux or Fedora images in one click. On any version you can register a cloud-init template you built yourself.
5. Install the CLI
brew install nebla-cloud/tap/nebla
Or download a binary for your platform from GitHub Releases. Then point it at your panel with an API token from a project:
nebla context create home
nebla server list
Upgrading
docker compose pull
docker compose up -d
Nebla migrates its database on start. Back up the pgdata volume before major upgrades.