Docs/ Premiers pas/ Migrer depuis Easypanel

Migrer depuis Easypanel

Déplacez vos services d’Easypanel vers sh0 un par un, en gardant Easypanel en ligne jusqu’à ce que chacun soit vérifié.

Avant de commencer

Ce guide suit la migration que nous avons menée nous-mêmes : une vingtaine de services de production issus de plusieurs projets, passés d’Easypanel à sh0 et comparés un à un à la production. La méthode est volontairement séquentielle : déployer un service sur sh0, le comparer à ce que sert Easypanel, puis passer au suivant.

Note
sh0 n’a pas aujourd’hui d’importateur Easypanel automatique. Chaque étape ci-dessous est manuelle, et chaque commande de cette page a été exécutée sur un vrai serveur avant d’être écrite ici.

1. Recenser ce qui tourne

Pour chaque service Easypanel, notez :

  • Sa source : dépôt Git et branche, le chemin de build si l’app vit dans un sous-dossier, et le nom du Dockerfile s’il n’est pas celui par défaut.
  • Ses variables d’environnement, y compris celles qui ne servent qu’au build.
  • Ses domaines et le port sur lequel l’app écoute.
  • Ses données : les bases qu’il utilise et les volumes ou montages où il écrit des fichiers.
  • S’il écoute seulement sur un port. Les consommateurs de file et les planificateurs n’écoutent pas, et se créent autrement sur sh0.

2. Préparer le serveur sh0

Installez sh0 sur un autre serveur, pas sur la machine Easypanel : les deux ont besoin des ports 80 et 443. Suivez Installation, puis créez le compte propriétaire.

Avant de déplacer quoi que ce soit, contrôlez l’hôte. La commande vérifie Docker, les ports, l’espace disque, les certificats et l’horloge, et sort avec 0 quand rien ne bloque :

Terminal
sudo sh0 doctor

Un exemple de rapport et le sens de chaque ligne sont dans Mises à jour et diagnostic.

3. Recréer chaque app

Créez chaque app sur sh0 à partir de la même source que sur Easypanel :

  • Depuis votre propre machine, sans hébergeur Git : sh0 push envoie le répertoire du projet et le construit, avec son Dockerfile ou, s’il n’y en a pas, en détectant la pile.
  • Depuis le même dépôt Git et la même branche : voir Déploiement Git. Dépôts privés, branches non standard et dépôts d’une autre organisation ont tous fonctionné dans notre migration.
  • Monorepos : réglez le chemin de build sur le sous-dossier de l’app, et le nom du Dockerfile s’il ne s’appelle pas Dockerfile. Un Dockerfile nommé se résout par rapport au chemin de build.
  • Services sans port (Celery, BullMQ, un planificateur) : créez-les en Worker (sans port). sh0 vérifie alors que le processus reste en vie au lieu d’attendre un port.

Recopiez les variables d’environnement avant le premier déploiement, puis comparez la nouvelle app à la production : mêmes codes de statut sur les mêmes chemins, même titre de page, même réponse du point de santé.

4. Déplacer les bases de données

Créez sur sh0 un serveur de bases de données de même moteur et de même version majeure que la source. Copiez ensuite les données avec les outils de sauvegarde et de restauration du moteur. L’exemple ci-dessous est PostgreSQL.

Remplacez EASYPANEL_DB par le conteneur de la base Easypanel (trouvez-le avec docker ps), et sh0-dbsrv-<name> par le conteneur du serveur de bases sh0. Utilisez le nom de base et l’utilisateur affichés dans les informations de connexion du serveur.

On the Easypanel server
docker exec EASYPANEL_DB pg_dump -U app -d app -Fc > app.dump
On the sh0 server
docker exec -i sh0-dbsrv-NAME pg_restore -U app -d app --no-owner --no-privileges < app.dump
docker exec sh0-dbsrv-NAME psql -U app -d app -tAc "select count(*) from orders"

Copiez le fichier de sauvegarde d’un serveur à l’autre avec scp ou rsync. Faites ensuite pointer le DATABASE_URL de l’app (ou son équivalent) vers le serveur de bases sh0 et redéployez l’app.

Tip
Les écritures faites sur Easypanel après la sauvegarde ne sont pas copiées. Pour une base qui change sans cesse, arrêtez l’app sur Easypanel juste avant la sauvegarde finale, ou planifiez la bascule à une heure creuse.

5. Déplacer fichiers et volumes

Les fichiers écrits par une app (envois, documents générés) vivent dans un volume Docker. Copiez le contenu du volume par une archive tar, puis ajoutez à l’app sur sh0 un volume au même chemin de montage :

On the Easypanel server
docker run --rm -v SOURCE_VOLUME:/data alpine:3.19 tar -czf - -C /data . > uploads.tgz
On the sh0 server
docker run --rm -i -v TARGET_VOLUME:/data alpine:3.19 tar -xzf - -C /data < uploads.tgz
docker run --rm -v TARGET_VOLUME:/data alpine:3.19 find /data -type f

Trouvez les noms des volumes avec docker volume ls sur chaque serveur. Sur sh0, les noms de volume commencent par sh0- suivi du nom de l’app.

Ce qui se comporte autrement

  • Mémoire : Easypanel ne pose aucune limite par défaut ; sh0 plafonne chaque app à 512 Mo tant que vous ne la relevez pas. Un backend Python à quatre workers en demandait davantage pendant notre migration, et la limite l’a arrêté jusqu’à ce que nous la relevions.
  • Noms de service : dans un projet, une app joint une autre app par son nom ou par <app>.internal, qui reste stable d’un déploiement à l’autre. Mettez à jour les noms d’hôte qui visaient des noms de service Easypanel.
  • Contexte de build : sh0 lit votre .dockerignore avec les règles de Docker ; un projet qui se construit sur Easypanel se construit de la même façon sur sh0.
  • Une base neuve révèle ce qu’une base ancienne cache : pendant notre migration, une chaîne de migrations ne se rejouait pas depuis une base vide, et une app créait ses tables depuis quatre workers à la fois. C’étaient des défauts des projets, pas des plateformes ; restaurer les données d’abord les évite.

6. Basculer les domaines

  1. La veille, abaissez le TTL de chaque enregistrement DNS que vous allez déplacer, pour que la bascule se propage vite.
  2. Ajoutez le domaine à l’app sur sh0.
  3. Faites pointer l’enregistrement DNS vers l’adresse IP du serveur sh0. sh0 obtient le certificat tout seul dès que l’enregistrement le désigne.
  4. Comparez le domaine en ligne à ce que servait Easypanel.
  5. Alors seulement, arrêtez le service sur Easypanel. Gardez ses données jusqu’à être sûr de ne pas devoir revenir en arrière.
Warning
Si un proxy Cloudflare se trouve devant le domaine, il peut masquer quel serveur répond. Vérifiez les en-têtes de réponse ou une page qui diffère entre les deux serveurs avant d’arrêter Easypanel.