Skip to content

Update the server

This page updates Musonic Server to a newer version, and explains what happens to your data and how to go back if needed. It is for the person who runs the server. The apps are updated separately, see the end of this page.

The server looks for new versions on GitHub every 6 hours (setting update_check, environment variable MUSONIC_UPDATE_CHECK, on by default). It never installs anything on its own: it tells you.

  • The console shows an alert “Musonic Server X is out” at the right end of the bar at the top. The Dashboard repeats it in a banner, “You have version …”, with a See the release button, and a counter appears next to Dashboard in the menu.
  • The Dashboard’s Versions card shows the installed version, the latest one, and Update available or Up to date. The same card covers the web player installed on the server.
The console's dashboard with the alert Musonic Server X is out in the top bar and in a banner with the See the release button, and the Versions card showing the installed version, the latest one and Update available.

Read the changes before you update: the release notes on the releases page (tags server-v…), or the list of versions.

  1. Go to the folder of the server.

    Terminal window
    cd ~/musonic-server
  2. Download the new image.

    Terminal window
    docker compose pull
  3. Start the server again with it.

    Terminal window
    docker compose up -d

    Docker replaces the container; your data folder stays. Music stops for a few seconds, the apps reconnect on their own.

  4. Check the version in the logs.

    Terminal window
    docker compose logs --tail 50 musonic-server

    The line musonic-server starting shows the new version.

  5. Remove the old image (optional).

    Terminal window
    docker image prune

With the tag :1 of the example compose file, pull takes the newest 1.x version: it never jumps to a 2.0 on its own. A 2.0 would say in its notes what to change first.

You have nothing to do: the server updates its database itself when it starts.

  • The database has a schema version. Each new version of the server brings the changes it needs (migrations), applied in order at start, each one entirely or not at all. The logs show database migrated to <n> (<name>) for each.
  • Before changing the database, the server copies it as it was, next to it: musonic.db.before-schema-<n> in the data folder (<n> is the first migration about to be applied). This copy is made once, and is there to go back by hand.
  • Many updates change nothing in the database: then no copy is made.
  • An older server refuses to open a database that a newer one has changed: it stops with database schema … is newer than this server …: update the server. Your data is not touched.

Besides that copy, the server backs up its database every day in backups/ inside the data folder (musonic-YYYY-MM-DD.db), the first time just after it starts. It keeps the last 14 (setting backup_days, MUSONIC_BACKUP_DAYS; 0 turns them off).

In the console, Settings and maintenance → Backups lists them, makes one now (Back up now) and downloads them. The console warns you when no backup was made for more than 2 days.

If a new version does not suit you, you can go back to the one you had.

If the update did not change the database (no database migrated line in the logs, no new musonic.db.before-schema-… file): put the old version back, that is all.

In compose.yml, write the exact version you had instead of 1, for example:

image: ghcr.io/doodzdev/musonic-server:1.2.0

then docker compose up -d. Put 1 back later to get updates again.

If the update changed the database, the old version refuses it. Go back to the copy made before the migration. What was done in the meantime (likes, plays, playlists since the update) is lost.

  1. Stop the server.

    Docker: docker compose down. Without Docker: sudo systemctl stop musonic-server.

  2. Move the current database aside, with its two companion files.

    In the data folder (~/musonic-server/data, or /var/lib/musonic-server):

    Terminal window
    mkdir newer
    mv musonic.db musonic.db-wal musonic.db-shm newer/

    (musonic.db-wal and musonic.db-shm may not exist: that is fine.)

  3. Put the copy made before the migration back.

    Terminal window
    cp musonic.db.before-schema-<n> musonic.db

    Take the newest one, the file with the highest <n>: it is the one this update made (older ones come from earlier updates). Without Docker, run the commands as the user of the service, or give the file back to it with chown.

  4. Start the old version (see above).

The apps are updated separately from the server: each has its own version and its own releases.

App How it learns about a new version How to update
Android A few seconds after it starts, the app checks GitHub for a newer Musonic release for Android. If there is one, a window says “Update available”, “Version X is available on GitHub”, with View release (opens the release page) and Cancel. You can also check yourself: the round button with your initial, at the top left of the main screens → About → Check for updates. Download and install the new APK from the release, over the old one: your accounts and downloads stay. See Install the Android app.
Web player on your server (/app/) The console’s Dashboard (Versions) and Settings and maintenance (Musonic Web on this server) show the latest version. Settings and maintenance → Musonic Web on this server → Update. Then reload the page in the browsers.
Web player of this site Nothing to do. It is updated with each new version of the web player: reload the page.
iPhone, iPad They use the web player: see the two lines above. Same.
The Android app with the window Update available, the text Version X is available on GitHub, and the buttons Cancel and View release.