Get started
Install
Nebla is one container plus a Postgres database. It talks to Proxmox VE only through its API, so it can run anywhere that reaches a Proxmox node on port 8006: a small VM on the same host, a mini PC, or a server elsewhere.
You need:
- A Proxmox VE 8 or 9 node or cluster.
- A Linux machine with Docker and Docker Compose.
- A URL for the panel, such as
https://panel.example.com. Passkeys need https with a domain name, orhttp://localhostfor a local trial.
Start Nebla
Make a folder and save this as compose.yaml:
name: nebla
services:
panel:
image: ghcr.io/nebla-cloud/nebla:0.2
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 seals the Proxmox token secrets it stores with it, and without it they can't be read.
Start Nebla and check that it answers:
docker compose up -d
curl -fs localhost:8080/v1/healthz
Create the first admin account
Open your PANEL_BASE_URL. The first visit shows a setup page where you create the first account, which becomes the panel admin.
The admin area then opens on Get Nebla ready, a checklist of four steps:
- Connect Proxmox. See Connect Proxmox.
- Turn on OS images.
- Add server types.
- Add an IP pool.
Once all four are done, anyone in a project can create servers. Set up the panel covers each step.
Environment variables
Nebla reads its settings from the environment. With Compose they go in .env.
| Variable | Required | What it does |
|---|---|---|
PANEL_DATABASE_URL | yes | Postgres URL. The compose file sets it for the bundled database. |
PANEL_BASE_URL | yes | Public URL of the panel. It builds console URLs and is the trusted origin for the API and console websockets. |
PANEL_SECRET_KEY | yes | At least 32 bytes. Seals Proxmox token secrets. Losing or changing it makes them unreadable. |
POSTGRES_PASSWORD | yes | Password for the bundled Postgres. |
PANEL_LISTEN | no | Listen address. Default :8080. |
PANEL_PORT | no | Host port Compose publishes the panel on. Default 8080. |
PANEL_SMTP_URL | no | Mail server for invite emails. Without it, you share invite links yourself. |
PANEL_TRUSTED_PROXIES | no | Comma-separated CIDRs or IPs of reverse proxies in front of the panel. Their X-Forwarded-For is then trusted for rate limits. |
PANEL_DEFAULT_QUOTA | no | Quota for projects that non-admin users create. |
PANEL_MAX_PROJECTS_PER_USER | no | How many projects a non-admin user may own. Default 3, and 0 means unlimited. |
PANEL_SMTP_URL looks like this, with smtps:// for TLS from the start:
PANEL_SMTP_URL=smtp://user:[email protected]:[email protected]
PANEL_DEFAULT_QUOTA defaults to:
PANEL_DEFAULT_QUOTA=servers=5,vcpu=8,memory_mb=16384,disk_gb=200,ips=5,volumes=5,volume_gb=100
Keys you leave out keep their default and 0 means unlimited. Projects a panel admin creates are always unlimited, and admins can change any project's quota later.
Changing the host in PANEL_BASE_URL makes existing passkeys stop working. Passwords keep working.
Behind a reverse proxy
Point your proxy at the panel port and pass websockets through, because the browser console uses them. Set PANEL_BASE_URL to the public https URL and add the proxy's address to PANEL_TRUSTED_PROXIES, so rate limits see the real client IP rather than the proxy's.
Upgrade
The compose file pins a minor release, such as 0.2. docker compose pull picks up patch releases within it:
docker compose pull
docker compose up -d
To move to a new minor release, change the tag in compose.yaml, then pull and start again. Nebla migrates its database on start. Back up first.
Back up
Everything Nebla knows lives in Postgres: users, projects, servers, IP assignments and the sealed Proxmox token secrets. Back up the database and keep PANEL_SECRET_KEY with it, because the backup is no use without the key.
docker compose exec -T postgres pg_dump -U nebla -Fc nebla > nebla-$(date +%F).dump
To restore into a fresh install with the same PANEL_SECRET_KEY:
docker compose up -d postgres
docker compose exec -T postgres pg_restore -U nebla -d nebla --clean --if-exists < nebla-2026-11-21.dump
docker compose up -d
Server disks and volumes live on Proxmox. Back them up there.
Next
Connect Proxmox with the one-line setup command, then work through Set up the panel.