Changer de serveur

Ce guide déplace une installation existante vers une autre machine : changement d'hébergeur, passage d'un serveur local à un VPS, remplacement d'une machine en fin de vie. Chaque étape dit ce que vous devez voir, et pourquoi elle compte.

La seule chose à retenir. Emportez tout le dossier de données, clé maîtresse comprise. Alors la licence n'a rien à réactiver, les téléphones se reconnectent d'eux-mêmes si l'adresse ne change pas, et la migration coûte quelques minutes. Sans la clé maîtresse, cela fonctionne quand même, mais chaque téléphone doit être appairé de nouveau et la clé de licence saisie de nouveau.

1. Ce qui décide de la facilité de la migration

Deux choses, et seulement deux :

L'adresse IP, le matériel, le système d'exploitation et l'hébergeur ne jouent aucun rôle. Avec l'installation fournie, l'identité de la machine vue par notre serveur de licences suit la clé maîtresse : emportez-la, et pour nous c'est la même machine.

2. Ce qui ne casse jamais

• Votre service ne s'arrête pas à cause de la licence. Que notre serveur de licences soit injoignable, ou qu'il voie une nouvelle machine, cela ne suspend jamais les envois. Au pire, l'écran Licence affiche un renouvellement en attente. Seule une licence retirée par nous (par exemple après un remboursement) suspend les envois.
• Après douze mois de possession, la licence n'a plus du tout besoin de nous contacter.
• Vos données restent lisibles et exportables dans tous les cas.

3. Avant de commencer

4. Voie A : déplacer l'archive complète (recommandé)

Cette voie conserve tout : historique, comptes, réglages, téléphones, licence.

Étape 1 : sauvegarder, puis arrêter l'ancienne passerelle

Sur l'ancienne machine :

sudo sms-gateway backup
sudo sms-gateway stop

backup écrit sms-gateway-backup-<date>.tar.gz dans le dossier courant ; stop arrête ensuite la passerelle pour de bon, afin que plus rien de nouveau ne s'écrive sur l'ancienne machine après la copie. Tant qu'aucune passerelle ne répond, les téléphones gardent les messages sortants et entrants dans leur file.

Vérifiez que l'archive contient la clé maîtresse :

tar tzf sms-gateway-backup-*.tar.gz | grep secret.key

Si secret.key n'apparaît pas, arrêtez-vous : vous seriez sur la voie B sans le savoir.

Sous Windows, voir Sauvegarde et restauration pour les commandes équivalentes.

Étape 2 : copier l'archive vers la nouvelle machine

scp sms-gateway-backup-20260901-023000.tar.gz user@new-machine:~/

L'archive contient toutes vos données et la clé maîtresse : ne la transférez que par un canal chiffré (scp, sftp), et supprimez les copies une fois la migration vérifiée.

Étape 3 : pointer le domaine vers la nouvelle machine (mode domaine)

Changez l'enregistrement A de votre domaine vers l'adresse IP de la nouvelle machine. Gardez le même domaine : les téléphones trouveront la nouvelle machine d'eux-mêmes.

Étape 4 : installer la passerelle sur la nouvelle machine

Lancez l'installation habituelle, avec le même mode qu'avant :

curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --domain sms.example.com --yes

(ou --lan pour un serveur local ; dans ce cas, donnez à la nouvelle machine le même nom que l'ancienne, voir Serveur local).

Ne créez pas de compte sur l'écran qui apparaît : vos comptes reviennent avec l'archive. Si le DNS n'a pas encore basculé, le script vous prévient ; le certificat est obtenu automatiquement dès qu'il a basculé.

Étape 5 : mettre l'archive en place

Sur la nouvelle machine, dans le dossier où se trouve l'archive :

sudo sms-gateway stop
docker run --rm -v sms-gateway_gateway-data:/data -v "$PWD:/in" alpine:3 sh -c '
  rm -rf /data/* &&
  tar xzf /in/sms-gateway-backup-20260901-023000.tar.gz -C /data'
sudo sms-gateway start

Cela remplace les données vides de l'installation neuve par les vôtres, clé maîtresse comprise. Si le nom du volume est différent sur votre machine (installation plus ancienne), retrouvez-le avec docker volume ls --filter label=com.docker.compose.volume=gateway-data.

Étape 6 : vérifier

Parcourez la section 8. Les téléphones se reconnectent en une ou deux minutes, et remettent les messages qu'ils avaient gardés.

5. Voie B : seulement une copie de la base

Prenez cette voie quand l'ancienne machine est perdue et que vous n'avez qu'une copie de la base : une sauvegarde téléchargée depuis Paramètres > Sauvegarde et export, ou un fichier .db. Elle ramène votre historique, vos contacts et vos réglages, mais pas la clé maîtresse.

1. Installez la passerelle sur la nouvelle machine (version identique ou plus récente que la copie), dans le mode voulu. Vous pouvez créer le premier compte : la copie le remplacera.
2. Placez la copie dans le dossier des sauvegardes et restaurez-la, comme décrit dans Restaurer une copie faite sur une autre machine, puis redémarrez avec sudo sms-gateway restart. Connectez-vous avec les comptes de la copie.
3. La licence : l'ancienne machine la détient encore, donc saisir directement votre clé est refusé avec un message disant que la clé est déjà utilisée sur une autre machine (le dashboard peut l'intituler comme une clé retirée : ce n'est pas le cas, et rien n'est suspendu). Libérez-la d'abord : dans votre espace client, cliquez sur Régénérer la clé. Cela détache toutes les machines de la licence et vous donne une nouvelle clé. Saisissez cette nouvelle clé dans Licence.
4. Appairez de nouveau chaque téléphone (section 7).
5. Webhooks : leurs secrets ne sont plus lisibles. Donnez à chaque webhook un nouveau secret par l'API (PATCH /api/v1/webhooks/{id} avec un nouveau secret) et mettez-le à jour du côté destinataire. Voir Webhooks.

Si vous avez encore l'ancien secret.key, vous pouvez éviter les étapes 3 à 5 : utilisez l'étape 5 de la voie A avec une archive complète, ou demandez-nous de l'aide.

6. La licence après le déménagement

Avec la voie A, il n'y a rien à faire : la nouvelle machine présente la même identité que l'ancienne. L'écran Licence affiche Licence active.

Si la licence voit une nouvelle machine (voie B, ou installation personnalisée qui a changé le nom du conteneur ou le dossier de données), voici ce que vous voyez, et rien de tout cela n'arrête les envois :

Le Journal des vérifications montre ces tentatives avec un refus signé pour une machine différente. Pour régler la situation, libérez la licence avec Régénérer la clé dans votre espace client, saisissez la nouvelle clé dans Licence, puis cliquez sur Vérifier maintenant. Détails dans Licence.

Faites-le à la fin de la migration, une fois sûr de garder la nouvelle machine : régénérer la clé empêche aussi l'ancienne machine de renouveler, ce qui complique un retour en arrière.

7. Les téléphones appairés

Un téléphone retient l'adresse de son QR code, son identité et son secret. La passerelle ne peut pas lui envoyer une nouvelle adresse.

Pour appairer de nouveau un téléphone :

1. Laissez-le d'abord remettre ses messages en attente s'il peut encore joindre une passerelle : Désappairer supprime les messages encore en file sur le téléphone.
2. Dans l'application, Désappairer, puis confirmez.
3. Dans le dashboard, Appareils > Appairer un appareil, et scannez le nouveau QR code (valable cinq minutes).

Vérifiez ensuite le quota journalier et les réglages de chaque SIM dans Appareils : voir Appareils.

Si un téléphone ne se reconnecte pas alors que rien n'aurait dû changer, vérifiez d'abord l'adresse : ouvrez https://<votre adresse>/health dans le navigateur du téléphone. Seulement ensuite, envisagez un nouvel appairage.

8. Vérifier après la migration

Ne démontez pas l'ancienne machine avant que chaque ligne soit vérifiée. Tant qu'elle existe, revenir en arrière prend une minute.

Une fois tout vérifié :

• Sur l'ancienne machine, sudo sms-gateway uninstall --purge supprime la passerelle et ses données. Ne le faites que lorsque vous en êtes sûr : c'est irréversible.
• Supprimez les copies transférées de l'archive, ou rangez-les chiffrées avec vos sauvegardes.
• Après une restauration par la voie B, la base mise de côté sous le nom gateway.db.pre-restore-... peut être supprimée (voir Sauvegarde et restauration).
• Planifiez les sauvegardes sur la nouvelle machine : voir Sauvegarde et restauration.

9. Revenir en arrière

10. Quand la nouvelle passerelle ne démarre pas

sms-gateway logs affiche la raison sur une ligne contenant gateway stopped. Après une migration, les causes habituelles sont :

La liste complète des messages de démarrage est dans Installation.

Réglages à reporter à la main : tout ce que vous avez changé ou décommenté dans le fichier .env de l'ancienne installation (GATEWAY_LOG_LEVEL, GATEWAY_TRUSTED_PROXIES, GATEWAY_ROUTING_MODE, GATEWAY_CARRIER_PREFIXES, GATEWAY_LOG_RETENTION_DAYS, GATEWAY_WEBHOOKS_ALLOW_PRIVATE_NETWORKS, GATEWAY_SECRET_KEY...). Une installation antérieure à cette version peut aussi avoir des variables ajoutées à la main dans son docker-compose.yml : reportez-les dans le nouveau .env. Tout ce qui se règle dans le dashboard, planification de la sauvegarde automatique comprise, voyage avec les données.