Add a documentation page for the stretch->buster migration

admindoc.md

@@ -55,6 +55,7 @@
     * [Hide services with Tor](/torhiddenservice)
     * [Utilisation de certificats autres que Let's Encrypt](/certificate_custom)
     * [A discussion about the advantages of using a VPN](/vpn_advantage)
+    * [Stretch->Buster migration procedure](stretch_buster_migration)
     * [(old) Jessie->Stretch migration procedure](jessie_stretch_migration)
 * Troubleshooting
     * [Changing the administration password](/change_admin_password)

admindoc_fr.md

@@ -55,6 +55,7 @@
     * [YunoHost avec un service caché Tor](/torhiddenservice)
     * [Utilisation de certificats autres que Let's Encrypt](/certificate_custom)
     * [Une discussion sur les avantages d'utiliser un VPN](/vpn_advantage)
+    * [Procedure de Migration Stretch->Buster](stretch_buster_migration)
     * [(vieux) Procedure de Migration Jessie->Stretch](jessie_stretch_migration)
 * Dépannage
     * [Changer le mot de passe d’administration](/change_admin_password)

stretch_buster_migration.md

@@ -0,0 +1,53 @@
+# Migrating an existing instance to Buster
+
+This page is dedicated to help you migrating an instance from YunoHost 3.8.x (running on Debian Stretch/9.x) to YunoHost 4.x (running on Debian Buster/10.x).
+
+## 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.
+
+- With that said, please be aware that this is a delicate operation. System administration is a complicated topic and covering every particular cases is quite hard. Therefore, if you host critical data and services, please [make backups](/backup). 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).
+
+## Migration procedure
+
+#### From the webadmin
+
+After upgrading to 3.8.5.x, go to Tools > Migrations to access the migrations interface. You will have to read carefully and accept the disclaimer then launch the migration. 
+
+#### From the command line
+
+After upgrading to 3.8.5.x, run : 
+
+```bash
+sudo yunohost tools migrations migrate
+```
+
+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.
+
+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).
+
+#### 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 tell that it's not working).
+
+## What to do after the upgrade
+
+#### Check that you actually are on Debian Buster and YunoHost 4.x
+
+For this, go in 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`.
+
+#### Check that no issue appeared in the diagnosis
+
+Also in the Diagnosis in the webadmin, 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).

stretch_buster_migration_fr.md

@@ -0,0 +1,53 @@
+# Migrer vers Buster
+
+L'objectif cette page est de décrire le processus de migration d'une instance en YunoHost 3.8.x (tournant sous Debian Stretch/9.x) vers YunoHost 4.x (tournant sous Debian Buster/10.x)
+
+## 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.
+
+- Néanmoins, vous devez être conscient qu'il s'agit d'une opération délicate. L'administration système est un sujet compliqué et couvrir tous les cas particuliers n'est pas chose aisée. En conséquence, si vous hébergez des données et des systèmes critiques, [faites des sauvegardes](/backup). Et 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
+
+#### Depuis la webadmin
+
+Après avoir mis à jour vers la version en 3.8.5.x, 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.
+
+#### Depuis la ligne de commande
+
+Après avoir mis à jour vers la version 3.8.5.x, lancez : 
+
+```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 en haut (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. 
+
+Notez que même si vous fermez la page d'admin, la migration continuera (par contre l'interface d'admin sera partiellement indisponible).
+
+#### 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érifiez que vous êtes véritablement sous Debian Buster / YunoHost 4.x
+
+Pour cela, vous pouvez aller dans la partie Diagnostic (section Système de base). (Vous pouvez aussi regarder ce qui est affiché à droite dans le pied de page de la webadmin). En ligne de commande, vous pouvez aussi utiliser `lsb_release -a` et `yunohost --version`.
+
+#### Vérifiez que le diagnostic ne rapporte pas de problème particulier
+
+Également dans la section Diagnostic 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 !).