# Installation

URL: https://docs.vaultpanel.net/getting-started/installation

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

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](https://docs.vaultpanel.net/getting-started/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:

```bash
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](https://github.com/VaultPanel/packages) and [installer.vaultpanel.net](https://installer.vaultpanel.net).

| System | `DB_ENGINE` (the first is the default) |
| --- | --- |
| Ubuntu 26.04 LTS | `MARIADB_12.3` (MariaDB 12.3), `MARIADB_11.8` (MariaDB 11.8) |
| Ubuntu 24.04 LTS | `MARIADB_12.3` (MariaDB 12.3), `MARIADB_11.4` (MariaDB 11.4), `MARIADB_10.11` (MariaDB 10.11) |
| Ubuntu 22.04 LTS | `MARIADB_11.4` (MariaDB 11.4), `MARIADB_10.11` (MariaDB 10.11), `MARIADB_10.6` (MariaDB 10.6) |
| Debian 13 | `MARIADB_12.3` (MariaDB 12.3), `MARIADB_11.8` (MariaDB 11.8) |
| Debian 12 | `MARIADB_12.3` (MariaDB 12.3), `MARIADB_11.4` (MariaDB 11.4), `MARIADB_10.11` (MariaDB 10.11) |

`DB_ENGINE=NONE` installs no database server. Copy the current checksum from https://github.com/VaultPanel/packages:

```bash
curl -sS https://installer.vaultpanel.net/v2/install.sh -o install.sh; \
echo "<checksum from github.com/VaultPanel/packages> install.sh" | \
sha256sum -c && sudo DB_ENGINE=MARIADB_12.3 bash install.sh
```

`DB_ENGINE` chooses the [database server for your websites and apps](https://docs.vaultpanel.net/getting-started/installation#choose-the-database-for-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:

```text
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](https://docs.vaultpanel.net/getting-started/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`.

| System | `DB_ENGINE` |
| --- | --- |
| Ubuntu 26.04 LTS | `MARIADB_12.3`, `MARIADB_11.8` |
| Ubuntu 24.04 LTS | `MARIADB_12.3`, `MARIADB_11.4`, `MARIADB_10.11` |
| Ubuntu 22.04 LTS | `MARIADB_11.4`, `MARIADB_10.11`, `MARIADB_10.6` |
| Debian 13 | `MARIADB_12.3`, `MARIADB_11.8` |
| Debian 12 | `MARIADB_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:

```bash
sudo DB_ENGINE=MARIADB_12.3 bash install.sh --port 9000
```

| Option | Environment variable | Default | What it does |
| --- | --- | --- | --- |
| `--db-engine <e>` | `DB_ENGINE` | the newest MariaDB | Database server for websites and apps, or `NONE`. |
| `--port <n>` | `VAULTPANEL_PORT` | `8090` | Port the panel listens on (1 to 65535). |
| `--url <address>` | `VAULTPANEL_URL` | `https://<public IP>:<port>` | Address people open the panel at, such as `https://panel.example.com`. |
| `--version <vX.Y.Z>` | `VAULTPANEL_VERSION` | the newest | Version of the `vaultpanel` package to install, or `latest`. |
| `--http` | `VAULTPANEL_HTTPS=off` | | Serve plain HTTP instead of HTTPS. Not recommended. |
| `--https` | `VAULTPANEL_HTTPS=on` | | Turn 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`](https://docs.vaultpanel.net/cli/server-command) and HTTPS with [`vaultpanel https`](https://docs.vaultpanel.net/getting-started/panel-https-and-domain). Because every option is also an environment variable, a downloaded copy can run as:

```bash
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](https://github.com/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:

```text
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](https://docs.vaultpanel.net/getting-started/backing-up-the-panel) (`vaultpanel-backup.timer`).
10. Adds the [`vaultpanel` command](https://docs.vaultpanel.net/cli/server-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.

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

These options only apply to an install from a copy:

| Option | Environment variable | Default | What it does |
| --- | --- | --- | --- |
| `--dir <path>` | `VAULTPANEL_DIR` | `/opt/vaultpanel` | Where VaultPanel is installed. |
| `--repo <url>` | | the VaultPanel repository | Git repository to install from. |
| `--branch <name>` | `VAULTPANEL_BRANCH` | | Install 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:

| Message | What to do |
| --- | --- |
| `port 8090 is already in use` | Stop what uses it, or pick another port with `--port`. |
| `port 3306 is already in use, so MariaDB cannot start there` | Stop what uses it, or install with `DB_ENGINE=NONE`. |
| `the vaultpanel package did not install` | Fix what the lines above it say, then finish with `sudo dpkg --configure -a`. |
| `the panel did not start` | The log above the message says why; `vaultpanel logs` shows more. |

More cases are in [Troubleshooting](https://docs.vaultpanel.net/troubleshooting).
