Skip to content

Backup and Restore

MT Showcase includes the mt-showcase-ctl tool for backing up and restoring MT Showcase data on Ubuntu and Windows.

Platform Tool
Ubuntu /opt/mt-showcase/bin/mt-showcase-ctl (/opt/mt-showcase points at the installed version)
Windows C:\Program Files\MT Showcase\bin\mt-showcase-ctl.exe

For macOS, see Back up on macOS.

What a backup contains

A backup contains:

  • the main application database, including changes made while the server is running;
  • the reporting database used for data gathering;
  • the media library, including the preview images Showcase generated for it;
  • the installation's encryption key, .auth-kek, from MT Showcase 26.10.0. It is stored in the backup folder as auth-kek, and a restore puts it back.

It does not contain:

  • hosted sites (the sites folder);
  • the TLS certificate;
  • your production_users.yaml.

Copy these yourself if you need them; see File locations.

The encryption key protects the single sign-on settings, personal folder links and stored SMTP passwords in the database. Without it they cannot be read after a restore onto a new computer. Because the key is in the backup, anyone who has a backup can read them: keep backups as securely as the server itself.

Backups made before 26.10.0

Backups made with earlier versions do not include .auth-kek, and they left out the generated preview images. If you restore such a backup onto a new computer, or after the data folder was lost, copy the original .auth-kek into the data folder before you start the server. To make the missing previews again, open Optimize Media Library in the Editor, which makes any missing previews when it starts.

Create a backup

For the most complete backup, stop the MT Showcase server first. A backup also works while the server is running: the Editor is paused until the backup finishes, and the MT Showcase client keeps running.

Ubuntu (run as the mt-showcase-server account, which owns the data):

sudo -u mt-showcase-server /opt/mt-showcase/bin/mt-showcase-ctl --backup

Windows (Command Prompt, signed in as the Windows user MT Showcase runs as):

"C:\Program Files\MT Showcase\bin\mt-showcase-ctl.exe" --backup

The backup is saved in a new subfolder of the backups folder, named after the date and the MT Showcase version:

  • Ubuntu: /var/lib/mt-showcase-server/backups
  • Windows: %LOCALAPPDATA%\MultiTaction\showcase\backups

Copy backups off the application computer, and protect them: they contain your user accounts, any visitor data and the installation's encryption key.

When a backup fails

Run the backup as the account the server runs as: on Ubuntu, mt-showcase-server; on Windows, the Windows user MT Showcase runs as. From MT Showcase 26.10.0, the backup stops with an error, rather than reporting success, when:

  • it finds no Showcase data at all. This usually means it was run from a different account, which cannot see the server's data. The message gives the paths it looked in and the account it ran as. On a computer that has never run the MT Showcase server, add --allow-empty to succeed anyway.
  • the database exists but the media library does not. To back up the databases without the media library on purpose, add --backup-skip assets.
  • the finished backup cannot be moved into its folder. The completed copy is kept in a temporary folder, named in the error message, so it is not lost.

Save a backup to a different folder

Give the folder with --backup-path. The backup is written directly into that folder, without a subfolder. Use a full path. On Ubuntu the folder must be writable by the mt-showcase-server account.

"C:\Program Files\MT Showcase\bin\mt-showcase-ctl.exe" --backup --backup-path D:\showcase-backup

If the folder already contains a backup, the command fails. Add --delete to replace the existing backup files in the folder. Other files in the folder are left alone.

Change the default backups folder

Set backup_root in production_users.yaml and restart the server; see Settings reference. For example:

backup_root: "D:/showcase-backups"

Leave data out of a backup

Use --backup-skip with one or more of db (main database), reporting (reporting database) and assets (media library), separated by commas. For example, to back up only the databases:

"C:\Program Files\MT Showcase\bin\mt-showcase-ctl.exe" --backup --backup-skip assets

Restore a backup

Restoring replaces your current data

A restore deletes the current databases and media library and replaces them with the backup.

  1. Stop the MT Showcase server and client; see Start and stop MT Showcase. The restore refuses to run while the server is running.

  2. Run the restore, giving the backup folder with --backup-path:

    Ubuntu:

    sudo -u mt-showcase-server /opt/mt-showcase/bin/mt-showcase-ctl --restore --backup-path /var/lib/mt-showcase-server/backups/<backup folder>

    Windows:

    "C:\Program Files\MT Showcase\bin\mt-showcase-ctl.exe" --restore --backup-path "%LOCALAPPDATA%\MultiTaction\showcase\backups\<backup folder>"

  3. Start the MT Showcase server.

On Ubuntu, from MT Showcase 26.10.0, a restore run with sudo as root gives every restored file the owner of the folder it is restored into, so the server can still write to them. Earlier versions left restored files owned by root; run the restore as mt-showcase-server, as shown above, or the server cannot change your data afterwards.

The backup must be from the same or an earlier version of MT Showcase. A backup from a newer version cannot be restored.

To leave data out of a restore, use --restore-skip with db, reporting or assets, separated by commas. For example, --restore-skip assets restores only the databases.

Exit codes

mt-showcase-ctl exits with 0 on success, 1 if the options are wrong, and 2 if the backup or restore failed. Check the output as well: if no backup folder is configured, the tool reports that it could not make a backup and still exits with 0.

Back up on macOS

mt-showcase-ctl is not supported on macOS. To back up MT Showcase on a Mac, quit MT Showcase, stop the server, and copy the whole ~/.mt-showcase folder. To restore, stop the server and put the copy back in place.

Backups and upgrades

Always create a backup before you upgrade MT Showcase, and copy it off the application computer. Do not rely on an automatic backup during an upgrade. See Upgrade.