Skip to content

Setup wizard

After the stack's first start, the first-run wizard runs in your browser. It opens automatically when you visit the server URL.

https://your-domain.tld

(or the IP, if no domain is configured — Vesana always starts over HTTPS, even without your own certificate, see Self-hosting → SSL/TLS)

If you don't arrive via the installer's setup link, the wizard first asks for the setup code — paste the code or the whole link. Where to find it: Install → Finding the setup code again.

Steps

1 — Welcome & language

German or English. Changeable later per user in preferences.

2 — Design

Choose a colour scheme (dark/light) and one of several bundled themes. The choice becomes the instance default — every new user starts with it. On first login each user may pick their own design once or keep the default; it can be changed any time later in their own settings.

3 — Server URL

The URL Vesana is reachable at (the BASE_URL environment variable from your installation). The wizard shows what's actually configured as BASE_URL and whether your input matches it — so a typo or a forgotten .env change stands out immediately, before you continue. This check doesn't set the URL anew, it only reports what the server actually sees.

4 — Administrator

Username and password for the first super admin (at least 8 characters, with a strength indicator to help). The username is a free-form name — admin is fine, no email address required. This account can't be deleted later unless another super admin exists.

5 — License

This step is optional. It first shows what works without a license — the limits of the Community edition as numbers (devices, tenants) and what a key adds. If you have a key, "I have a license key" opens the input field; otherwise just Next. If the installer already received a key, the step shows "License active" with edition and limits (see License). Later at any time under Admin → System → Licence.

6 — First tenant

A tenant groups devices, checks, users and notifications — per customer, site or environment, for example. One is enough to start; any name works, e.g. "Homelab", "Office" or a customer name. You can rename it at any time.

Add more tenants later: Admin → Users & access → Tenants.

7 — Size (sizing)

Four profiles to choose from — Small / Medium / Large / Extra large (XL), roughly staged by expected service count. Details on the concrete values per profile: Resources → Performance.

The choice is saved and, on finishing the wizard, applied immediately on a best-effort basis (container restart with the matching values). If the responsible background service isn't reachable at that moment, the choice stays saved as a recommendation — you then apply it manually under Admin → System → Resources → Performance. The sizing choice never lowers the Postgres memory values the installer derived from RAM — it can only raise them.

8 — Summary

All inputs are summarised, then "Start Vesana". Vesana waits until the services are back up after the sizing step and the active checker is running, then logs you in. On the first start this can take a few minutes — just keep the window open, it continues on its own.

Afterwards the start page shows a welcome overview once: how Vesana checks (agent, active checker, collector — which fits what), the way to the first device, to notifications and to the documentation. Hide it with ✕.

E-mail sending (SMTP) is set up under Admin → Notifications → E-mail & Messages, recipients and channels under Alerting.

What the wizard no longer asks

One former wizard step is gone from the first-run flow, because it has a safe default and rarely needs changing:

  • Admin access mode (open / IP allowlist / dedicated container) — always starts with the open default, configurable under Admin access & split container

A separate "localhost monitoring" step, which used to optionally create a few checks on the stack itself, is also no longer part of the wizard.

Since 10/2026 also gone: the SMTP step (it could only do part of what the settings under Admin → Notifications → E-mail & Messages do) and the question about setting up automatically (that feature no longer exists).

Setup was skipped — resuming it

If the wizard was accidentally interrupted, you can revisit it at https://your-domain.tld/setup as long as no admin has been created yet.

Once an admin exists, /setup redirects automatically to the login page.

Next