Install the panel

Install the VMStack panel with one command on a fresh Debian 13 or Ubuntu server: what it asks, what it checks, what it installs and what to do next.

The panel is installed by one script, run as root on a fresh server that meets the panel server requirements. It takes about four minutes.

Before you start#

  1. Create the server: Debian 13 (recommended), Ubuntu 24.04 or Ubuntu 26.04, at least 2 vCPU, 2 GiB of memory and 20 GB free.
  2. Point the panel's domain at it: an A record (and AAAA when the server has IPv6) for a name such as panel.example.com. Wait until it resolves.
  3. If the domain is proxied by Cloudflare, read Cloudflare first.

Run the installer#

As root:

curl -fsSL https://vmstack.eu/install.sh | bash

If you have a licence key from your vmstack.eu account, add it and the panel is licensed as soon as it is up:

curl -fsSL https://vmstack.eu/install.sh | bash -s -- --licence-key VMS-STD-XXXX-XXXX-XXXX-XXXX

Replace VMS-STD-XXXX-XXXX-XXXX-XXXX with your key. Your vmstack.eu account shows this line ready to copy, with your key in it, on its install page.

The questions are read from the terminal, so piping the script into bash works. For an install without questions, see Installer options.

Check the script first (optional)#

install.sh is signed with the VMStack release key (Ed25519). To check the signature before running it:

curl -fsSLO https://vmstack.eu/install.sh
curl -fsSLO https://vmstack.eu/install.sh.sig
cat > release.pem <<'EOF'
-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEAyZBr4Zu85G9r8sumjrEU64KXxNw6BzTLBR/UgVDpmz0=
-----END PUBLIC KEY-----
EOF
base64 -d install.sh.sig > install.sh.bin
openssl pkeyutl -verify -pubin -inkey release.pem -rawin -in install.sh -sigfile install.sh.bin && bash install.sh

openssl prints Signature Verified Successfully and the installer starts. Any other answer means the file is not the one VMStack published: do not run it. The same key signs every panel and agent release; see Security.

The three questions#

  1. The panel's domain, such as panel.example.com. It becomes the panel's address, https://panel.example.com.
  2. The first administrator's e-mail.
  3. The e-mail for Let's Encrypt (certificate expiry notices). Press Enter to use the administrator's.

The installer then prints a summary (version, domain, channel, the server's size, what it installs) and asks Install? (yes/no).

What it checks#

Before anything is installed, and before the questions where it can:

  • root, systemd, a supported system and architecture, not OpenVZ or WSL;
  • at least 2 vCPU, 2 GiB of memory and 20 GB free on /opt and on /var/lib/postgresql;
  • that the server is not a VMStack node, has nothing on ports 80 and 443, no other web server and no PostgreSQL with other databases;
  • after the questions: that the domain's A and AAAA records point at this server.

Each failure says what is wrong and what to do, and nothing has been changed. The messages and their fixes are listed in Troubleshooting the panel and licensing.

What it does#

  1. Installs the few tools it needs, then downloads the newest release of the stable channel and checks it: the release manifest's signature, the archive's size and SHA-256, and that no file in the archive points outside it. A bad download stops here, on a clean server.
  2. Installs nginx, PostgreSQL, Redis (Valkey where the distribution has no Redis), certbot and nftables from the distribution, and PHP 8.5 from the distribution or, when the distribution does not ship 8.5, from the sury (Debian) or ondrej (Ubuntu) repository, with that repository's key checked against a fingerprint built into the script and an apt pin limiting it to PHP packages.
  3. Creates the vmstack system user and unpacks the release into /opt/vmstack/releases/<version>/. The code is owned by root and cannot be changed by the web application.
  4. Creates the database and its user, generates every secret (database and Redis passwords, APP_KEY) into /opt/vmstack/shared/.env, and never prints them.
  5. Tunes PHP-FPM, opcache, PostgreSQL, Redis, nginx and the kernel for the server's CPUs and memory, and adds a 2 GiB swap file when the server has no swap and less than 8 GiB of memory.
  6. Runs the database migrations and creates the certificate authority and the standard images.
  7. Writes the systemd units: PHP-FPM, the queue workers, the scheduler and the console relay, all under vmstack-panel.target, plus a daily database dump at 02:30, the updater and the automatic-update timer.
  8. Gets a Let's Encrypt certificate. If that fails, the install still finishes with a self-signed certificate and the summary says why, in red (see below).
  9. Turns on the firewall: SSH, 80 and 443 in, everything out.
  10. Starts the panel and checks it end to end: /up answers, every unit runs, a worker takes a job from every queue, and the console relay answers through nginx. A failure stops before the sign-in link is printed and says which part failed.
  11. Creates the first administrator and, with --licence-key, activates the licence.

The full log is /var/log/vmstack-panel-install.log (secrets are never written to it).

The summary#

VMStack panel 0.6.0 is installed.

  Panel:        https://panel.example.com
  Sign in:      https://panel.example.com/invite/…   (once, valid 72 hours)
  Certificate:  Let's Encrypt, renews by itself
  Tuned for:    4 vCPU, 8 GiB (PHP workers 32, PostgreSQL 1638 MiB, Redis 512 MiB)
  Panel IP:     203.0.113.10 (the address nodes allow; change VMSTACK_PANEL_IP if behind NAT)
  • Sign in is a one-time link, valid 72 hours, that sets the administrator's password. No password is ever printed. Continue with First-time setup.
  • Certificate says "self-signed" in red when Let's Encrypt refused, with its reason. The API and the console do not work in browsers until a trusted certificate is in place. Fix the cause (usually DNS, or port 80 not reachable from the internet), then run vmstack-panel cert.
  • Licence appears when you passed --licence-key: activated, or why not. A failed activation never stops the install; enter the key on the panel's Welcome screen instead.
  • Panel IP is the address nodes see the panel come from.

Warning: Back up /opt/vmstack/shared/.env together with the database. The certificate authority that every node trusts is stored in the database, encrypted with the APP_KEY in .env. The daily dumps in /opt/vmstack/shared/backups stay on the same server: copy them elsewhere, or set up Panel backup.

If the install stops#

Run the same command again. Every step records itself when it is done, and the installer continues from the first step not done, with the answers it saved in /etc/vmstack/panel.conf. A licence key is not saved: pass --licence-key again if you need it.

Run on a server where the panel is already installed, the installer only says so and points to vmstack-panel update and vmstack-panel repair.

Where things are#

Path What
/opt/vmstack/releases/<version>/ The code of each release (the last 3 are kept)
/opt/vmstack/current Link to the release in use
/opt/vmstack/shared/.env Configuration and secrets (root:vmstack, 0640)
/opt/vmstack/shared/storage/ Logs, uploads, sessions (storage/logs/laravel-<date>.log, 14 days)
/opt/vmstack/shared/backups/ Daily database dumps (the last 7) and dumps taken before updates
/opt/vmstack/shared/downloads/ The agent installer and binaries that nodes download
/etc/vmstack/panel.conf The installer's answers and options; no secrets
/usr/local/sbin/vmstack-panel The management command
/var/log/vmstack-panel-install.log The install log

Workers, the scheduler and the relay log to the journal: journalctl -u 'vmstack-*'. nginx logs to /var/log/nginx/vmstack-panel.access.log and .error.log; query strings are never logged.