Panel backup and restore

Back up the VMStack panel itself (database, application key, certificates) encrypted to SFTP or S3, and restore it on a new server without touching the nodes.

The panel's own backup holds what you need to bring the panel back on another server: its database, its application key and its certificate authority, encrypted with a key only you hold. It does not back up your customers' servers; those are in Backups.

Without the panel's database and APP_KEY, the nodes cannot be managed again without enrolling each one anew, because they trust the panel's certificate authority. Set this up before you add customers.

What is backed up#

Each run makes one file, vmstack-panel-YYYYmmdd-HHMMSS.tar.age: a tar archive encrypted with age, holding

File Content
database.dump The panel's PostgreSQL database (pg_dump, custom format)
app-key.txt APP_KEY and APP_PREVIOUS_KEYS. Everything the panel encrypts in its database opens only with them.
env The panel's .env as it was, for reference (it holds passwords)
pki/ The certificate authority and the panel's client certificate, with their keys (ca.crt, ca.key, client.crt, client.key), in case the application key is lost
manifest.json The panel's version, the date and the SHA-256 of each file
README.txt The restore steps below

Set it up#

Go to Backups › Overview and open Panel backup.

1. The encryption key#

Choose one:

  • Download key: the panel makes an age key pair. Download the key file (you are asked for your password again) and keep it somewhere other than the panel's server. No backup runs until the key has been downloaded once: a backup only the panel itself could open would be lost with the panel.
  • Use your own key: paste the public key (age1…) of a key pair you made with age-keygen. The panel never holds the secret part, so there is nothing to download.

Make a new key starts again with a new key. Earlier backups still open only with the key they were made with; keep it as long as you keep them.

2. Where and when#

Field What to choose
Destination An SFTP destination whose host key the panel knows, or an S3-compatible destination, from Backups › Destinations. Files go into panel/ under the destination's base directory. Or this panel's own machine (a copy there does not survive losing the machine). Node directories and NFS are not offered.
Schedule Off, every day, or every week on a Day, At (UTC) an hour
Keep How many of the newest successful backups to keep, 1 to 90 (default 7). Older ones are deleted from the destination after each backup.

Click Save (changing the destination asks for your password). Back up now makes one within a minute.

An S3 upload is a single request, so a backup can be at most 5 GB.

3. Check it#

Backups of the panel lists every run: when, scheduled or by whom, the result or the error, the size, the file and where it went. A scheduled backup that cannot run (no key downloaded, no destination) appears there as a failed run with the reason. Every change and run is also in the audit log (panel_backup.*). The panel does not send mail when a backup fails: check the list.

From a shell on the panel server, sudo -u vmstack php /opt/vmstack/current/artisan vmstack:panel-backup --now makes a backup at once.

Restore on a new server#

Restoring is done by hand, on a freshly installed panel. It replaces everything the new panel knows. The nodes need nothing: they trust the certificate authority in the backup. The same steps are on the Panel backup page and in each backup's README.txt.

  1. Have the key: the key file you downloaded, or the identity of your own age key.

  2. Decrypt and unpack. Install age (apt install age on Debian and Ubuntu), then in an empty directory:

    age -d -i vmstack-panel-backup-key.txt vmstack-panel-YYYYmmdd-HHMMSS.tar.age | tar -x
    
  3. Install a panel on the new server with the installer, at the same version as the backup (manifest.json says which) or newer, and with the same domain. Point the domain at the new server first. Then stop it:

    systemctl stop vmstack-panel.target
    
  4. Restore the database into the new panel's database. This replaces everything in it:

    sudo -u postgres pg_restore --clean --if-exists --no-owner --role=vmstack --dbname=vmstack database.dump
    
  5. Put the application key back: in /opt/vmstack/shared/.env, set APP_KEY (and APP_PREVIOUS_KEYS, when there is one) to the values in app-key.txt. Keep the new .env's database and Redis passwords.

  6. Migrate and start:

    sudo -u vmstack php /opt/vmstack/current/artisan migrate --force && systemctl start vmstack-panel.target
    
  7. Check: sign in, open Infrastructure › Nodes and wait for every node to answer.

Warning: Do not restore a backup into a panel older than the one that made it.

When the new panel has another address than the old one, allow it on the nodes' agent port if you restricted that port to the panel's address (see Node firewall).

The licence after a restore#

The licence is bound to the panel's install, which is stored in the database, so a restored panel keeps its licence. Turn the old panel off for good: two panels using the same install are flagged by vmstack.eu.

The installer's daily dump#

Separately from the above, the installer's timer dumps the database every night at 02:30 into /opt/vmstack/shared/backups/ on the panel's own server, keeping the last 7 (vmstack-panel backup makes one now). Those dumps are not encrypted and do not contain APP_KEY; to restore from one you also need the .env of the same panel. Updates also leave a dump there before they migrate (pre-<version>.sql.gz, the last 3).