Skip to main content

Migrating from 11.x to 12.x

This page is dedicated to help you migrating an instance from YunoHost 11.x (running on Debian Bullseye) to YunoHost 12 (running on Debian Bookworm).

Important notes​

  • The YunoHost team did its best to make sure that the migration is as smooth as possible and was tested over the course of several months in several cases.

  • Please backup your data and server! This migration is a complex operation and covering every pitfall is quite hard. And in any case, be patient and attentive during the migration.

  • Please don't rush into thinking that you should need to reinstall your system from scratch thinking it would be "simpler" (sigh). (A common attitude is to be willing to reinstall a server at the slightest complication...). Instead, if you happen to run into issues, we encourage you to try to investigate and understand what's going on and reach for help on the chat and the forum.

  • You should watch the known issues at the bottom of this page, to be sure your migrations will work properly.

Migration procedure​

You first need to ensure your system is up to date. The migration is available starting with the version 11.3.

It is recommended to run the migration from the command line, but it can still be done from the webadmin.

From the webadmin​

Go to Tools > Migrations to access the migrations interface. You will have to read carefully and accept the disclaimer then launch the migration.

Note that even if you close the webadmin page for some reason, the migration will continue in the background (but the webadmin will be partially unavailable).

From the command line​

Run :

sudo yunohost tools migrations run

then read carefully and accept the disclaimer.

During the migration​

Depending on your hardware and installed apps and packages, the migration can take up to one or two hours.

Logs will be displayed in the webadmin's modal window in the middle of the page. They will also be browsable after the migration like any other major operation under Tools > Logs.

If the migration fails at some point​

If the migration fails, the first thing to try should be relaunch it. If it still doesn't work, your should ask for help to the community (please provide error message, full logs and any context element that would help debugging the issue).

After the migration​

Check that you actually are on Debian Bookworm and YunoHost 12.x​

Go to Diagnosis (category Base system) or look at the bottom-right of the webadmin to check YunoHost's version.

From the command line, you can use lsb_release -a and yunohost --version.

Run the new pending migrations​

Some more migrations appeared after the upgrade:

  • Rebuilding the virtualenvs of your Python apps
  • Migrate from PostgreSQL 13 to 15

You should run those as soon as possible to ensure your apps work properly.

Agreeing to the new Terms of Service via command line​

YunoHost 12.x now requires that you agree to the new Terms of Service. After reading and accepting them you can run:

yunohost tools migrations run 0031_terms_of_services --accept-disclaimer

Check the Diagnosis​

In the webadmin Diagnosis section, make sure that no specific issue appeared after running the migration (for example a service that crashed for some reason).

Check that your applications are working​

Test that your applications are working. If they aren't, you should try to upgrade them (it is also a good idea to upgrade them even if they are working anyway).

If your app is broken and you were already with the latest version, you can rerun the upgrade thanks to the -F|--force option:

yunohost app upgrade --force APP_NAME

Current known issues after the migration​

Please check the issues FAQ.