From efbec8167c336ea36aa8d0facd4fa349f354adba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Pi=C3=A9dallu?= Date: Thu, 18 Jul 2024 11:17:02 +0200 Subject: [PATCH 1/4] Add pages about migration from 11 to 12 --- .../bullseye_bookworm_migration.fr.md | 83 ++++++++++++++++++ .../bullseye_bookworm_migration.md | 85 +++++++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md create mode 100644 pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md diff --git a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md new file mode 100644 index 00000000..55bc8f01 --- /dev/null +++ b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md @@ -0,0 +1,83 @@ +--- +title: Migrer de 11.x vers 12.x +template: docs +taxonomy: + category: docs +routes: + default: '/bullseye_bookworm_migration' +--- + +L'objectif cette page est de décrire le processus de migration d'une instance en YunoHost 11.x (tournant sous Debian Bullseye) vers YunoHost 12.x (tournant sous Debian Bookworm). + +## Notes importantes + +- L'équipe de YunoHost a fait de son mieux pour que cette migration se passe autant en douceur que possible. Elle a été testée durant plusieurs mois et sur plusieurs types d'installations. + +- [Faites des sauvegardes](/backup) de votre serveur et de vos données ! Cette migration est une opération complexe et éviter tous les problèmes possibles est difficile. Dans tous les cas, soyez patients et attentifs durant la migration. + +- Ne vous précipitez pas à vouloir faire une réinstallation de votre système en pensant que cela serait "plus simple" (sigh). (Une attitude qui revient régulièrement est de vouloir réinstaller son système à la moindre complication...). À la place, si vous rencontrez des problèmes, nous vous encourageons à investiguer, chercher à comprendre et [trouver de l'aide sur le chat ou le forum](/help). + +## Procédure de migration + +Vous devez d'abord vous assurer que votre système est à jour. La migration est disponible à partir de la version 11.2.FIXME:. + +Il est recommendé de lancer la migration depuis la ligne de commande, mais elle peut très bien être effectuée depuis la webadmin. + +### Depuis la webadmin + +Allez dans Outils > Migrations pour accéder à l'interface de migration. Il vous faudra ensuite lire l'avertissement attentivement et l'accepter pour lancer la migration. + +Notez que même si vous fermez la page d'admin, la migration continuera (par contre l'interface d'admin sera partiellement indisponible). + +### Depuis la ligne de commande + +Lancez simplement : + +```bash +sudo yunohost tools migrations migrate +``` + +puis lisez attentivement l'avertissement et les instructions. + +## Pendant la migration + +En fonction de votre matériel et des paquets installés, la migration peut prendre jusqu'à une ou deux heures. + +Les logs seront affichés dans la barre de message au centre de la page (vous pouvez approcher la souris dessus pour voir l'historique en entier). Ils seront également consultable après coup (comme les autres opérations) dans Outils > Journaux. + +### Si la migration a crashé / échoué à un moment + +Si la migration a échoué a un moment donné, la première chose à faire est de tenter de la relancer. Si cela ne fonctionne toujours pas, il vous faut [trouver de l'aide](/help) (prière de fournir le/les messages correspondants ou tout élément qui vous fait penser que ça n'a pas marché). + +## Choses à vérifier après la migration + +### Vérifier la version de Debian et YunoHost + +Pour cela allez dans l'outil de diagnostics ou regardez en bas de la page de la webadmin. En ligne de commande vous pouvez utiliser `lsb_release -a` et `yunohost --version`. + +### Exécuter les nouvelles migrations + +Après la mise à niveau, de nouvelles migrations sont apparues : + +* La recréation des virtualenvs de vos applis Python +* La migration de PostgreSQL 13 à 15 + +Vous devez les lances le plus tôt possible pour garantir le bon fonctionnement de vos applis. + +### Vérifiez que le diagnostic ne rapporte pas de problème particulier + +Dans l'outil de diagnostics de la webadmin, vérifiez qu'il n'y a pas de problème apparu suite à la migration (par exemple un service qui ne tournerais plus...) + +### Vérifiez que les applications fonctionnent + +Vérifiez que vos applications installées fonctionnent... Si elles ne fonctionnent pas, il est recommandé de tenter de les mettre à jour. (ou bien de manière générale, il est recommandé de les mettre à jour même si elles fonctionnent !). + +Si votre app est cassée et que vous étiez déjà sur la dernière version d'une application, vous pouvez relancer la mise à jour grâce à l'option `--force`: + +```bash +yunohost app upgrade --force NOM_APP +``` + +## Soucis connus après la migration + +Veuillez consulter [la FAQ des problèmes de migration](/bookworm_migration_issues_faq) (en anglais). diff --git a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md new file mode 100644 index 00000000..51e727bf --- /dev/null +++ b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md @@ -0,0 +1,85 @@ +--- +title: Migrating from 11.x to 12.x +template: docs +taxonomy: + category: docs +routes: + default: '/bullseye_bookworm_migration' +--- + +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](/backup)! 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](/help). + +- **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.2.FIXME:. + +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 + +Just run : + +```bash +sudo yunohost tools migrations run +``` + +then read carefully and accept the disclaimer. + +## During the migration + +Depending on your hardware and packages installed, the migration might take up to a few hours. + +The logs will be shown in the message bar (you can hover it to see the whole history). They will also be available after the migration (like any other operations) in Tools > Logs. + +### If the migration crashed / failed at some point + +If the migration failed at some point, it should be possible to relaunch it. If it still doesn't work, you can try to [get help](/help) (please provide the corresponding messages or whatever makes you say that it's not working). + +## What to do after the upgrade + +### Check that you actually are on Debian Bookworm and YunoHost 12.x + +For this, go to Diagnosis (category Base system) or look at the footer of the webadmin. In 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. + +### 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: + +```bash +yunohost app upgrade --force APP_NAME +``` + +## Current known issues after the migration + +Please check the [issues FAQ](/bookworm_migration_issues_faq). From eade845c04fa82a1196f21b4a0d22f08c006f6c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Pi=C3=A9dallu?= Date: Thu, 18 Jul 2024 11:19:53 +0200 Subject: [PATCH 2/4] Migration to bookworm from version 11.3 --- .../16.bullseye_bookworm/bullseye_bookworm_migration.fr.md | 2 +- .../16.bullseye_bookworm/bullseye_bookworm_migration.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md index 55bc8f01..8d97676b 100644 --- a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md +++ b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.fr.md @@ -19,7 +19,7 @@ L'objectif cette page est de décrire le processus de migration d'une instance e ## Procédure de migration -Vous devez d'abord vous assurer que votre système est à jour. La migration est disponible à partir de la version 11.2.FIXME:. +Vous devez d'abord vous assurer que votre système est à jour. La migration est disponible à partir de la version 11.3. Il est recommendé de lancer la migration depuis la ligne de commande, mais elle peut très bien être effectuée depuis la webadmin. diff --git a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md index 51e727bf..c180e023 100644 --- a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md +++ b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/bullseye_bookworm_migration.md @@ -21,7 +21,7 @@ This page is dedicated to help you migrating an instance from YunoHost 11.x (run ## Migration procedure -You first need to ensure your system is up to date. The migration is available starting with the version 11.2.FIXME:. +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 8ee45172518b5c06d3cea273f0b50ecfcaaa546d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Pi=C3=A9dallu?= Date: Thu, 18 Jul 2024 11:21:20 +0200 Subject: [PATCH 3/4] Add empty issues_faq about bookworm migration --- .../16.bullseye_bookworm/issues_faq.md | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md diff --git a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md new file mode 100644 index 00000000..c0301977 --- /dev/null +++ b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md @@ -0,0 +1,56 @@ +--- +title: Bookworm migration isues FAQ +template: docs +taxonomy: + category: docs +routes: + default: '/bookworm_migration_issues_faq' +--- + +This page lists all the known issues encountered after a migration from YunoHost 11 to 12. + +## Python apps + +After upgrading, your python apps should be unavailable because their virtual environment (venv) needs to be rebuilt. + +To do that you can run the pending migrations in `Webadmin > Update`. + +The apps below won't be automatically repaired, you need to force-upgrade them manually instead with `yunohost app upgrade -F APP`. + +Apps which won't be automatically repaired and need a force upgrade: + +TODO: list those apps + +FIXME:??!!! If needed, you can disable the automatic rebuild for a specific python app, by removing the dedicated file ending with `.requirements_backup_for_bullseye_upgrade.txt` before applying the migration. You can find this file near the venv (Python virtual environment) of your app inside `/var/www`. + + + From 91bed035ff92a5d74677c0024a2a11960db719df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Pi=C3=A9dallu?= Date: Thu, 18 Jul 2024 12:12:45 +0200 Subject: [PATCH 4/4] Update issues_faq --- .../55.upgrade/16.bullseye_bookworm/issues_faq.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md index c0301977..54430198 100644 --- a/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md +++ b/pages/02.administer/15.admin_guide/55.upgrade/16.bullseye_bookworm/issues_faq.md @@ -9,6 +9,8 @@ routes: This page lists all the known issues encountered after a migration from YunoHost 11 to 12. +If the suggested solutions don't work, please [ask for help](/help). + ## Python apps After upgrading, your python apps should be unavailable because their virtual environment (venv) needs to be rebuilt. @@ -23,6 +25,14 @@ TODO: list those apps FIXME:??!!! If needed, you can disable the automatic rebuild for a specific python app, by removing the dedicated file ending with `.requirements_backup_for_bullseye_upgrade.txt` before applying the migration. You can find this file near the venv (Python virtual environment) of your app inside `/var/www`. +## Error 500 everywhere + +The web server, nginx, might need a restart before being fully operational. Please run this command: + +``` +sudo systemctl restart nginx +``` +