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, or http://localhost for 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:

  1. Connect Proxmox. See Connect Proxmox.
  2. Turn on OS images.
  3. Add server types.
  4. 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.

VariableRequiredWhat it does
PANEL_DATABASE_URLyesPostgres URL. The compose file sets it for the bundled database.
PANEL_BASE_URLyesPublic URL of the panel. It builds console URLs and is the trusted origin for the API and console websockets.
PANEL_SECRET_KEYyesAt least 32 bytes. Seals Proxmox token secrets. Losing or changing it makes them unreadable.
POSTGRES_PASSWORDyesPassword for the bundled Postgres.
PANEL_LISTENnoListen address. Default :8080.
PANEL_PORTnoHost port Compose publishes the panel on. Default 8080.
PANEL_SMTP_URLnoMail server for invite emails. Without it, you share invite links yourself.
PANEL_TRUSTED_PROXIESnoComma-separated CIDRs or IPs of reverse proxies in front of the panel. Their X-Forwarded-For is then trusted for rate limits.
PANEL_DEFAULT_QUOTAnoQuota for projects that non-admin users create.
PANEL_MAX_PROJECTS_PER_USERnoHow 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.