Upgrading
Maki’s database migrations apply on startup, and they cannot be reversed.
Docker
Section titled “Docker”With Docker Compose, pull the new image and recreate the container:
docker compose pulldocker compose up -dup -d recreates the container only when the image changed. Your data stays in the /config and
/library mounts.
With docker run, pull the image, remove the old container and run your original command again:
docker pull ghcr.io/orbitmpgh/maki:latestdocker stop maki && docker rm makiTo upgrade on purpose instead of following latest, pin a version tag such as
ghcr.io/orbitmpgh/maki:X.Y.Z. CI publishes X.Y.Z, X.Y and X tags for each release. The latest
tag only moves on stable releases.
Unraid
Section titled “Unraid”Update the container from the Docker tab. Unraid keeps the settings from your template. See Install on Unraid and Unraid paths and appdata.
Windows app
Section titled “Windows app”The Windows app checks for a new version two minutes after it starts, then every six hours, and
downloads it in the background. When one is ready, choose Restart to update to
Your database, settings and logs are in %LOCALAPPDATA%\Maki, outside the install folder, so an
update leaves them alone. The backup under What happens on startup
applies to the app too. See Windows app.
Linux tarball
Section titled “Linux tarball”The tarball does not update itself. Stop the service, unpack the new tarball and replace
/opt/maki with it. Your data stays in /var/lib/maki. Then start the service again:
sudo systemctl stop makitar -xzf Maki-<version>-linux-x64.tar.gzsudo rm -rf /opt/makisudo cp -r maki /opt/makisudo chown -R maki:maki /opt/makisudo systemctl start makiUse linux-arm64 in the file name on an ARM machine. Maki backs up the database before a new version
applies its migrations, as described under What happens on startup. See
Linux.
What happens on startup
Section titled “What happens on startup”When a new version starts with unapplied migrations, Maki:
- Backs up the database and settings into the
backupsfolder under/config. - Applies the migrations.
- Starts the server.
The backup comes first because migrations are forward-only. There is no down migration, so once one has run, the only way back is a backup taken before it.
If the database was written by a newer Maki than the one running, Maki logs an error and the Health page shows it, with a link to the backups. Running an older build against a newer database can corrupt data, so restore the pre-upgrade backup or upgrade again.
After an upgrade, Settings has a New tab listing the settings added since the version you upgraded from. It stays until the next upgrade.
Going back
Section titled “Going back”To roll back to the version you had before:
- Start the older image. Pin its tag, such as
ghcr.io/orbitmpgh/maki:X.Y.Z, in your compose file or on thedocker runline. - Restore the backup taken just before the upgrade. Maki stages the restore and exits, then applies it on its next start. Something has to start it again: Docker’s restart policy, systemd or the Windows app. A bare start stays down until you start it. See Backup and restore.
The database you restored over is kept for 7 days next to the restored one, in case you need it back.
Restoring a backup taken by a newer version is refused, so use the pre-upgrade backup. Some changes made after that backup are kept on restore, such as revoked API keys. Passwords, SSO links and other account changes go back to the backup’s state.
Upgrading from a single-user Maki
Section titled “Upgrading from a single-user Maki”The first page asks you to set a username and password. Your library, history and tracker connections are already attached to that account.