Skip to content

Install

One command, run as root — that's all. A fresh Debian 13 in a dedicated VM is recommended (see Prerequisites), but it works just as well on Ubuntu or alongside other services:

curl -fsSL https://vesana.org/install | bash

If curl is missing (minimal Debian), wget works too:

wget -qO- https://vesana.org/install | bash

As root, without sudo

The installer needs root privileges (Docker, /opt, systemd). On Debian, sudo is often not even installed — so log in as root first: su - (Debian) or sudo -i (Ubuntu), then run the one-liner.

What the installer does

[1/6] Checking system            – architecture, RAM, ports 80/443
[2/6] Installing prerequisites   – openssl/curl, Docker (if needed)
[3/6] Downloading Vesana         – compose file + configuration template
[4/6] Configuration              – server address, license key (optional)
[5/6] Generating secrets         – passwords, encryption key
[6/6] Starting Vesana            – pull images, start stack, wait for health

Long steps (Docker install, image download) run quietly in the background — the full output goes to /var/log/vesana-install.log.

You are asked exactly two things:

  1. Address where Vesana should be reachable in the browser (suggested: the detected server IP — Enter accepts it)
  2. License key — Enter skips it (free Community Edition)

Then head to the browser: https://<your-address>/setup starts the setup wizard. The certificate warning on first visit is expected (self-signed certificate).

The installer ends by printing a setup link that carries a one-time code (…/setup?setup_token=…). If you open /setup by hand, the wizard asks for that code — it is in the installer output and in .env as VESANA_SETUP_TOKEN. Nobody else can set up the instance in the minutes between installation and completion. Once setup is complete the code no longer matters.

Active Collector & first network scan

The installation automatically sets up the Active Collector (active checks like ping/SNMP/HTTP directly from the Vesana server). It installs itself as soon as the setup wizard is finished — typically 1–3 minutes later. On first contact it looks up the reachable networks once; after your first login Vesana asks whether it should set up the network automatically — the first devices then appear under Discovery.

Status and any errors: Admin → Agents & Collectors → Active checker (+ diagnostic log).

Back up the FIELD_ENCRYPTION_KEY

Losing the key = losing data

At the end of step 5 the installer prints the FIELD_ENCRYPTION_KEY. It protects encrypted fields (e.g. SNMP communities) and is deliberately not part of backups. If it is lost, that data is permanently unrecoverable.

Right after installation:

  1. Copy the key from the output (also in /opt/vesana/secrets/)
  2. Store it in a password manager (Bitwarden, 1Password, KeePass)
  3. Additionally keep an offline or separately stored copy

Unattended install (automation)

Every question has an environment variable — so the installer runs without a terminal (Ansible, cloud-init, CI):

VESANA_BASE_URL=https://monitoring.example.com \
  bash <(curl -fsSL https://vesana.org/install)
Variable Meaning
VESANA_BASE_URL server address (required for unattended)
VESANA_LICENSE_KEY license key (empty = Community)
VESANA_DIR install directory (default /opt/vesana)
VESANA_REGISTRY_USER / VESANA_REGISTRY_TOKEN private registry (Enterprise)
VESANA_NO_START 1 = install but do not start

Re-run

The installer is re-runnable: if /opt/vesana/.env already exists, the configuration is left untouched (no secret rotation) — it only makes sure the stack is running. For a complete reinstall: docker compose -f /opt/vesana/docker-compose.prod.yml down -v (deletes all data!), then rm /opt/vesana/.env and run the one-liner again.

Next