Installation

Install VaultPanel on a fresh Ubuntu or Debian server with the checked one-command installer, and choose its options.

Last updated

The installer sets VaultPanel up on a fresh server and runs it as a service that starts at boot. It takes a few minutes and ends by printing the panel's address and a setup token.

Check the system requirements first: Ubuntu 22.04, 24.04 or 26.04, or Debian 12 or 13, with systemd, run as root.

Install

Update the system and install the required packages

Before running the installer, update the system and install the packages the install command needs: curl downloads the installer, and sudo runs it. As root:

apt update && apt -y upgrade && apt -y install curl wget sudo

Download, check and run the installer

Choose your system and the database server for your websites and apps. The command carries the current release's checksum, which changes with each release; each release publishes it at github.com/VaultPanel/packages and installer.vaultpanel.net.

Run the installer with the database server you want for your websites and apps.

curl -sS https://installer.vaultpanel.net/v2/install.sh -o install.sh; \
echo "37779be96c4732cf4fdf5a39a6786b1de60f5361c44bcce4a0f2baaf26495d57 install.sh" | \
sha256sum -c && sudo DB_ENGINE=MARIADB_12.3 bash install.sh

The checksum is the current release's, as published at installer.vaultpanel.net and github.com/VaultPanel/packages. sha256sum -c runs the installer only if the download matches it.

DB_ENGINE chooses the database server for your websites and apps; without it, the installer takes the newest MariaDB for your system. MySQL 8.4 and 8.0 come in a later version.

Note the address and setup token

When it finishes, the installer prints the panel's address, a setup token and the certificate's fingerprint:

VaultPanel is installed.

  Open:          https://203.0.113.10:8090/setup
  Setup token:   15d59a807f148df64628dd4ca0abd16c
                 (creates the owner account; it stops working once you have)
  Database:      MariaDB 12.3 for websites and apps

  The panel uses a self-signed certificate, so your browser warns once: check that it
  shows this SHA-256 fingerprint, then continue.
    <the certificate's SHA-256 fingerprint>
  For a trusted certificate, give the panel a domain: System > Panel Domain.

  On this server: vaultpanel shows the address and status; vaultpanel help lists the rest.

Lost it? sudo vaultpanel shows the address, and sudo vaultpanel setup-token shows the token until the owner account exists.

Open the panel

Open the address in your browser. It warns about the certificate once: check that the SHA-256 fingerprint it shows matches the one the installer printed, then continue. sudo vaultpanel https shows the fingerprint again.

Paste the setup token and create the owner account. The server the panel runs on is already connected and shows as This server. Continue with the quick start.

Choose the database for websites and apps

DB_ENGINE chooses the database server the installer sets up for your websites, apps and the app installer (WordPress, Joomla, Drupal, Laravel), on port 3306. The panel's own database is separate: a MariaDB in Docker on port 3307.

SystemDB_ENGINE
Ubuntu 26.04 LTSMARIADB_12.3, MARIADB_11.8
Ubuntu 24.04 LTSMARIADB_12.3, MARIADB_11.4, MARIADB_10.11
Ubuntu 22.04 LTSMARIADB_11.4, MARIADB_10.11, MARIADB_10.6
Debian 13MARIADB_12.3, MARIADB_11.8
Debian 12MARIADB_12.3, MARIADB_11.4, MARIADB_10.11
  • Without DB_ENGINE, a new install gets the newest MariaDB for its system (the first in its row). An update installs nothing unless DB_ENGINE asks.
  • DB_ENGINE=NONE installs no database server. You can install MariaDB later from the server's Database server card in the panel.
  • When the system's own packages have the chosen version, they are used. Otherwise the installer adds MariaDB's repository (/etc/apt/sources.list.d/vaultpanel-mariadb.list, from deb.mariadb.org) after checking that its signing key has MariaDB's fingerprint. Security updates then come with apt upgrade.
  • A server that already has MariaDB or MySQL keeps it, and updating VaultPanel never changes the database server.
  • MySQL 8.4 and 8.0 come in a later version; the installer refuses MYSQL_8.4 and MYSQL_8.0 until then.

Installer options

Pass options after bash install.sh, or after bash -s -- when the installer is piped from curl:

sudo DB_ENGINE=MARIADB_12.3 bash install.sh --port 9000
OptionEnvironment variableDefaultWhat it does
--db-engine <e>DB_ENGINEthe newest MariaDBDatabase server for websites and apps, or NONE.
--port <n>VAULTPANEL_PORT8090Port the panel listens on (1 to 65535).
--url <address>VAULTPANEL_URLhttps://<public IP>:<port>Address people open the panel at, such as https://panel.example.com.
--version <vX.Y.Z>VAULTPANEL_VERSIONthe newestVersion of the vaultpanel package to install, or latest.
--httpVAULTPANEL_HTTPS=offServe plain HTTP instead of HTTPS. Not recommended.
--httpsVAULTPANEL_HTTPS=onTurn on HTTPS for a panel installed before it was the default.

--port, --url and --http choose how a new panel is set up. Afterwards, change the address with vaultpanel url and HTTPS with vaultpanel https. Because every option is also an environment variable, a downloaded copy can run as:

sudo VAULTPANEL_PORT=9000 bash install.sh

Checking what you install

  • The installer. Each release publishes install.sh at installer.vaultpanel.net, with its SHA-256 in the VaultPanel/packages README and at https://installer.vaultpanel.net/v2/install.sh.sha256. The install command above checks it before running anything.
  • The package repository. The installer adds VaultPanel's repository only after checking that its signing key has VaultPanel's fingerprint, and apt then checks every package against that key:
79B3 4D79 D2A7 D0DE 54A3 D906 B62A 47C2 ED27 75A6

The repository is in /etc/apt/sources.list.d/vaultpanel.list and the key in /etc/apt/keyrings/vaultpanel.asc.

  • MariaDB's repository, when it is needed, is trusted only with MariaDB's signing key fingerprint, 177F 4010 FE56 CA33 3630 0305 F165 6F24 C74C D1D8.

What the installer does

  1. Installs curl, openssl, Node.js 22 from NodeSource (system-wide, at /usr/bin/node) and Docker with Docker Compose. An existing Docker, the snap included, is reused.
  2. Installs the MariaDB chosen with DB_ENGINE for websites and apps, unless the server already has a database server.
  3. Adds VaultPanel's package repository and installs the vaultpanel package: the panel, ready to run, in /opt/vaultpanel. The package then sets the panel up (steps 4 to 10), on a new install and after every upgrade.
  4. Creates the vaultpanel system user the panel runs as, and writes /opt/vaultpanel/.env with new random secrets: the encryption key, the setup token, and the passwords of the panel's database and Redis. Root writes the file; the vaultpanel group may only read it.
  5. Makes a self-signed certificate for the panel's port in /etc/vaultpanel/tls/, valid for 10 years. The panel can read the key but not change it.
  6. Starts the panel's own MariaDB (127.0.0.1:3307) and Redis (127.0.0.1:6379, with a password) in Docker. They come back after a reboot and stay separate from the MariaDB for websites and apps.
  7. Updates the panel's database to the installed version.
  8. Installs two systemd services that start at boot: vaultpanel (the web interface and API) and vaultpanel-worker (background jobs). Both run as the unprivileged vaultpanel user in a systemd sandbox: no capabilities, a read-only system, and write access only to the panel's folder, /var/lib/vaultpanel/panel. Only one step runs as root: before the panel starts, it connects this server to the panel by installing or updating the agent.
  9. Schedules a daily backup of the panel (vaultpanel-backup.timer).
  10. Adds the vaultpanel command and a login banner, and opens the panel's port in UFW when the firewall is on.

Running the installer again is safe: it keeps .env and all data, and installs a newer package when there is one.

Install from a copy of the repository

To try code that is not released yet on a test server, clone the VaultPanel repository with a GitHub account that has access, and run the installer from the copy. It installs that copy's code into /opt/vaultpanel and builds it on the server; later updates come from the same repository.

git clone https://github.com/VaultPanel/VaultPanel.git
sudo bash VaultPanel/install.sh

These options only apply to an install from a copy:

OptionEnvironment variableDefaultWhat it does
--dir <path>VAULTPANEL_DIR/opt/vaultpanelWhere VaultPanel is installed.
--repo <url>the VaultPanel repositoryGit repository to install from.
--branch <name>VAULTPANEL_BRANCHInstall a branch, such as main, instead of a release tag. Not together with --version.

If the install fails

The installer stops at the first problem and says what to fix, starting with VaultPanel was not installed:. Common cases:

MessageWhat to do
port 8090 is already in useStop what uses it, or pick another port with --port.
port 3306 is already in use, so MariaDB cannot start thereStop what uses it, or install with DB_ENGINE=NONE.
the vaultpanel package did not installFix what the lines above it say, then finish with sudo dpkg --configure -a.
the panel did not startThe log above the message says why; vaultpanel logs shows more.

More cases are in Troubleshooting.