Installation

Cette page vous mène de l'achat à un téléphone appairé qui envoie son premier SMS. Elle ne suppose aucune connaissance préalable du produit. Comptez environ un quart d'heure, dont la moitié en téléchargement.

L'installation tient en une commande. Un script installe Docker s'il manque, télécharge les fichiers de la dernière version, vérifie qu'ils n'ont pas été altérés, écrit la configuration, démarre la passerelle et installe une commande d'exploitation, sms-gateway. Vous n'avez rien à compiler et aucune adresse de serveur à saisir.

Ce que vous installez

La passerelle est un seul programme, qui écoute sur un seul port et range tout dans un seul dossier de données (un volume Docker). Elle tourne dans un conteneur Docker, sur votre machine.

Conséquence pratique : sauvegarder le dossier de données sauvegarde toute l'installation, et le déplacer déplace la passerelle (voir Sauvegarde et restauration et Changer de serveur).

Ce qu'il vous faut

Rien n'est compilé sur votre machine : la passerelle est publiée prête à l'emploi pour les processeurs amd64 et arm64, et Docker choisit la bonne. Une petite machine suffit : la passerelle consomme très peu de mémoire, et la plus petite offre de la plupart des hébergeurs suffit pour démarrer.

Le parcours en cinq étapes

Étape 1 : créer votre compte et acheter

Rendez-vous sur sms-gateway.araylab.com. Le bouton Acheter vous demande d'abord de vous connecter : saisissez votre adresse e-mail et vous recevez un lien de connexion. Aucun mot de passe à retenir. Vous arrivez dans votre espace client, vide pour l'instant.

Le paiement est géré par Gumroad, qui émet aussi la facture et s'occupe de la TVA. À Madagascar, le paiement par Mobile Money (MVola, Orange Money, Airtel Money) est validé à la main : la licence apparaît après cette validation, pas instantanément.

Une fois le paiement confirmé, vous recevez un e-mail annonçant que la licence est prête. Pour votre sécurité, cet e-mail ne contient pas la clé : il vous renvoie vers votre espace client.

Étape 2 : copier votre clé de licence

Dans l'espace client, la licence affiche sa clé, au format XXXX-XXXX-XXXX-XXXX, avec un bouton pour la copier. Les instructions d'installation et le lien de téléchargement de l'application Android y apparaissent aussi, dès que la licence est active.

Vous pouvez revenir à tout moment afficher la clé, et la régénérer si elle a fuité (voir Régénérer la clé).

Étape 3 : lancer la commande d'installation

Sur la machine qui hébergera la passerelle, dans un terminal.

Linux (VPS, Oracle Cloud, serveur local, Raspberry Pi) :

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

Sans option, le script vous pose deux questions : s'il peut installer Docker s'il manque, et si vos téléphones joindront la passerelle par un nom de domaine ou sur le réseau local (voir Choisir le mode). Pour tout répondre d'avance :

# Avec un nom de domaine : HTTPS automatique (recommandé)
curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --domain sms.example.com --yes

# Sur le réseau local, sans nom de domaine
curl -fsSL https://sms-gateway.araylab.com/install.sh | sudo bash -s -- --lan --yes

macOS : la même commande, avec Docker Desktop installé et démarré au préalable. L'installation va dans ~/sms-gateway, et la commande sms-gateway est placée dans ce dossier.

Windows (Docker Desktop requis), dans PowerShell ouvert en administrateur :

irm https://sms-gateway.araylab.com/install.ps1 | iex

Sous Windows, le script ne pose aucune question sur le mode : il installe en mode réseau local par défaut. Pour changer cela, définissez ces variables dans la même fenêtre PowerShell avant de lancer la commande :

$env:SMSGW_DOMAIN = "sms.example.com"
irm https://sms-gateway.araylab.com/install.ps1 | iex

Si Docker Desktop manque, le script Windows propose de l'installer avec winget, puis s'arrête et vous demande de redémarrer Windows, de lancer Docker Desktop une fois, et de relancer la commande. Il installe dans %ProgramData%\SmsGateway, ouvre le port 8080 dans le pare-feu Windows pour les réseaux privés en mode réseau local, puis ouvre le tableau de bord dans votre navigateur.

À la fin, chaque script affiche l'adresse du tableau de bord et le code d'installation qui sert à créer le compte administrateur (étape 4). Sous Linux et macOS, sms-gateway url réaffiche l'adresse et sms-gateway setup-code réaffiche le code, tant qu'aucun compte n'existe.

Vous préférez lire le script d'abord ? Envoyer un script téléchargé directement dans bash, c'est lui faire confiance. Vous pouvez le télécharger, le lire, puis le lancer :

curl -fsSL https://sms-gateway.araylab.com/install.sh -o install.sh
less install.sh
sudo bash install.sh --domain sms.example.com

Le script, lui, vérifie tout ce qu'il télécharge ensuite avec une empreinte SHA-256 publiée : un fichier qui ne correspond pas arrête l'installation avant que quoi que ce soit ne soit installé.

Ce que fait le script, dans l'ordre

1. Il vérifie qu'il tourne en root sur une machine Linux amd64 ou arm64 (ou sur macOS).
2. Il installe Docker s'il manque, par le script officiel de Docker, après vous l'avoir demandé (ou sans demander avec --yes).
3. Il trouve la dernière version publiée (ou celle donnée par --version), télécharge ses fichiers et vérifie leur empreinte.
4. Il demande le mode si aucune option ne l'a fixé. En mode domaine, il vérifie que le domaine pointe vers cette machine et que les ports 80 et 443 sont libres. Un problème donne un avertissement et une question, pas un arrêt net : vous pouvez corriger le DNS ensuite.
5. En mode réseau local, il installe avahi-daemon, qui rend le nom <nom-de-la-machine>.local résolvable sur votre réseau.
6. Il écrit la configuration dans /opt/sms-gateway/.env, lisible par root seulement. Une configuration existante est conservée : relancer la commande met la passerelle à jour sans effacer vos réglages.
7. Il télécharge la passerelle, la démarre et attend qu'elle réponde (deux minutes au plus).
8. Il installe la commande sms-gateway et affiche l'adresse du tableau de bord, le code d'installation et les étapes suivantes.

Les options (Linux et macOS)

Comment les options interagissent :

• Sans --domain ni --lan, le script demande. Avec --yes et aucun mode lors d'une première installation, il s'arrête : il n'y a pas de mode par défaut, parce que le mauvais donne des téléphones qui ne se connectent jamais.
• Lors d'une nouvelle exécution sur une installation existante, le mode et le port déjà enregistrés sont conservés. Redonner --domain ou --lan change de mode : l'adresse publique change, et les téléphones déjà appairés doivent être appairés à nouveau.
• --port n'est pris en compte qu'à la première installation. Ensuite, le port enregistré dans la configuration l'emporte ; modifiez plutôt GATEWAY_PORT dans le fichier .env (voir Les réglages modifiables).
• --yes répond aussi oui aux avertissements. En mode domaine, une installation avec un DNS faux ou des ports 80/443 occupés continue quand même : la passerelle fonctionne, mais le HTTPS ne fonctionnera pas tant que vous n'aurez pas corrigé la cause.

Étape 4 : ouvrir le tableau de bord, créer l'administrateur, coller la clé

Ouvrez l'adresse affichée par le script. Une installation neuve ouvre l'écran Créer le premier compte : Jeton d'installation, nom, adresse e-mail, mot de passe. Le mot de passe doit faire au moins 12 caractères. Ce premier compte est le superadministrateur, et l'écran qui le crée se ferme définitivement dès qu'un compte existe.

Le jeton d'installation est le code d'installation affiché à la fin du script. Il prouve que la personne qui crée le compte a accès à la machine : sans lui, le premier inconnu tombant sur une passerelle fraîchement installée sur internet pourrait s'en faire l'administrateur. Si vous ne l'avez plus sous les yeux :

Le code disparaît dès que le compte est créé : les commandes ci-dessus répondent alors qu'il n'y en a plus, et c'est normal.

La création du compte ne vous connecte pas : l'écran confirme la création, puis vous envoie vers l'écran de connexion, où vous saisissez l'adresse e-mail et le mot de passe que vous venez de choisir.

Une fois connecté, une fenêtre Activer cette passerelle apparaît. Collez la clé copiée à l'étape 2. Les espaces, les tirets et les minuscules sont acceptés. Il n'y a rien d'autre à saisir : la passerelle sait déjà joindre notre serveur de licences.

Si notre serveur ne répond pas à ce moment-là, la fenêtre indique Notre serveur ne répond pas. Votre clé est quand même enregistrée et rien n'est suspendu : la passerelle envoie normalement et retente l'activation d'elle-même. Une panne de notre côté n'est jamais traitée comme une licence invalide. Détails dans Licence.

Étape 5 : installer l'application Android et appairer le téléphone

1. Téléchargez l'application depuis votre espace client, sur le téléphone lui-même ou sur un ordinateur puis copiée sur le téléphone. L'application n'est pas sur le Play Store : le lien n'est donné qu'aux détenteurs d'une licence.
2. Installez-la. Android vous demande d'autoriser l'installation depuis la source utilisée (navigateur ou gestionnaire de fichiers). Autorisez-la pour cette installation.
3. Dans le tableau de bord, ouvrez Appareils et cliquez sur Appairer un appareil. Un QR code apparaît, avec un code de secours pour un téléphone dont l'appareil photo ne fonctionne pas. Il est valable cinq minutes et ne sert qu'une fois ; Générer un nouveau code vous en donne un autre.
4. Dans l'application, scannez le QR code. Le téléphone se connecte à la passerelle et apparaît en ligne dans Appareils, avec ses cartes SIM.
5. Envoyez un SMS de test depuis Envoi rapide, puis répondez-y depuis un autre téléphone : la réponse apparaît dans Conversations.

L'application demande à être exemptée de l'optimisation de la batterie et affiche une notification permanente : c'est ce qui la maintient active en arrière-plan. Gardez le téléphone en charge. Tout ce qui concerne les téléphones (SIM, quota journalier, maintien en éveil) est dans Appareils.

Si vous saisissez l'adresse à la main au lieu de scanner, saisissez-la en entier, avec https:// ou http:// (https://sms.example.com ou http://server.local:8080). Sans cela, l'application suppose une connexion HTTPS, ce qui échoue sur une installation en réseau local.

Choisir le mode : domaine ou réseau local

C'est le seul vrai choix de l'installation, et il décide de l'adresse que composent les téléphones. Cette adresse est inscrite dans chaque QR code d'appairage, puis conservée par le téléphone. Une mauvaise adresse donne un QR code qui se scanne parfaitement et un téléphone qui n'atteint jamais rien.

Choisissez le mode domaine dès que vous le pouvez : il n'a aucune des réserves ci-dessous.

Ce qu'implique le mode réseau local

• L'application Android n'accepte de connexion non chiffrée que vers un nom .local. Une adresse IP simple comme http://192.168.1.20:8080 est refusée par le téléphone. C'est pourquoi l'installeur utilise http://<nom-de-la-machine>.local:8080.
• Vérifiez que le téléphone résout ce nom avant d'aller plus loin : ouvrez http://<nom-de-la-machine>.local:8080/health dans le navigateur du téléphone, connecté au même wifi. Une réponse {"status":"ok",...} signifie que l'appairage peut fonctionner.
• La session du tableau de bord circule en clair sur votre réseau. L'installeur définit GATEWAY_INSECURE_COOKIES=true, sinon les navigateurs refuseraient de vous garder connecté en HTTP simple. Acceptable sur un réseau d'entreprise que vous maîtrisez, pas sur un wifi partagé.
• Le nom de la machine ne doit pas changer, puisqu'il est inscrit dans les QR codes. Le renommer oblige à appairer de nouveau les téléphones.
• Un wifi invité isole souvent ses appareils : le téléphone voit internet mais pas la machine. Le test /health ci-dessus le révèle. Placez les téléphones sur le réseau interne.

Tout ce qui est propre à ce parcours (adresse fixe, wifi invité, accès depuis l'extérieur) est dans Serveur local.

Ce qu'implique le mode domaine

• Le DNS doit pointer vers la machine avant que le certificat puisse être obtenu. Le script vous prévient si ce n'est pas le cas ; le certificat est obtenu automatiquement dès que le DNS est bon.
• Les ports 80 et 443 doivent être joignables depuis internet, le port 80 compris : il sert à prouver que vous possédez le domaine. Ouvrez-les dans le pare-feu de la machine et chez votre hébergeur, qui filtre souvent lui aussi.
• Rien d'autre n'est exposé : un petit serveur web (Caddy) gère le HTTPS devant la passerelle, qui elle-même n'écoute que sur la machine.
• Si un proxy comme Cloudflare est placé devant le domaine, désactivez-le le temps d'obtenir le certificat.

La commande sms-gateway

Installée sous Linux et macOS, elle se lance en root (ou avec sudo) depuis n'importe quel dossier.

Relancer la commande d'installation a le même effet que sms-gateway update.

Sous Windows, il n'y a pas de commande sms-gateway. Ouvrez PowerShell dans %ProgramData%\SmsGateway et utilisez directement Docker Compose :

Gardez l'ordinateur allumé et Docker Desktop réglé pour démarrer avec Windows : la passerelle ne tourne que lorsque Docker Desktop tourne.

Arrêter ou redémarrer ne fait rien perdre. Pendant que la passerelle est arrêtée, les téléphones gardent les messages sortants et entrants dans leur propre file et les transmettent à son retour.

Régénérer la clé

Dans l'espace client, Régénérer la clé remplace votre clé de licence par une nouvelle. Faites-le si la clé a fuité (un ticket de support, une capture d'écran, un ancien prestataire), ou pour libérer la licence avant d'installer sur une autre machine.

La passerelle installée ne s'arrête pas. En revanche, elle ne peut plus renouveler son activation tant qu'elle porte l'ancienne clé : ouvrez Licence dans le tableau de bord et saisissez-y la nouvelle clé. Deux régénérations doivent être espacées d'au moins une minute.

Dépannage

Commencez toujours par sms-gateway status, puis sms-gateway logs.

Accès réseau

La machine a besoin d'un accès HTTPS sortant vers :

Si bck1.araylab.com est bloqué, rien ne cesse de fonctionner, mais l'écran de licence continuera d'indiquer que notre serveur ne répond pas.

Les réglages modifiables

L'installeur écrit la configuration dans /opt/sms-gateway/.env (lisible par root seulement ; sous Windows, %ProgramData%\SmsGateway\.env). Pour une installation standard, vous n'avez rien à ajouter. Tout ce que vous ajustez au quotidien (fenêtre d'envoi, nouvelles tentatives, fuseau horaire, notifications, règles de routage...) se règle dans le tableau de bord, dans Paramètres et les écrans associés, pas ici : voir Paramètres. Aucun réglage du tableau de bord n'a de variable équivalente, et aucune variable ci-dessous ne se modifie depuis le tableau de bord.

Après avoir modifié le fichier .env, appliquez le changement avec sms-gateway restart (sous Windows : docker compose up -d dans le dossier d'installation). Une mise à jour ou une nouvelle exécution de l'installeur conserve le fichier ; elle ne réécrit que la version et, si vous redonnez --domain ou --lan, les lignes du mode.

Dans le fichier .env

Ces lignes sont écrites par l'installeur. Vous pouvez les modifier, en sachant ce que chacune commande.

Le fichier liste aussi, en commentaire, les réglages ci-dessous (une mise à jour ajoute cette liste une fois à un .env écrit par une version antérieure). Retirez le # devant une ligne pour l'utiliser, puis redémarrez. Le docker-compose.yml fourni transmet chacun d'eux à la passerelle ; absent ou vide, la passerelle applique sa valeur par défaut. Comme ils vivent dans .env et non dans docker-compose.yml, une mise à jour les conserve.

Interactions à connaître :

• Le mode tient en quatre lignes qui vont ensemble : GATEWAY_PUBLIC_URL, GATEWAY_DOMAIN, COMPOSE_PROFILES et GATEWAY_BIND (plus GATEWAY_INSECURE_COOKIES). En changer une sans les autres donne, par exemple, un site HTTPS qui fonctionne et des téléphones qui ne s'appairent pas. Pour changer de mode ou de domaine, relancez l'installeur avec --domain ou --lan : il les réécrit ensemble.
• Changer GATEWAY_PUBLIC_URL ne met pas à jour les téléphones déjà appairés : ils gardent l'adresse de leur QR code. Appairez-les de nouveau après un tel changement.
• Un GATEWAY_TRUSTED_PROXIES trop large (par exemple 0.0.0.0/0) permet à n'importe qui de se faire passer pour n'importe quelle adresse IP et de contourner le blocage après échecs de connexion. Laissé vide, la passerelle voit chaque visiteur avec l'adresse du proxy, et tous partagent les mêmes limites.

Réglages avancés

La passerelle lit aussi les deux variables ci-dessous. Elles ne figurent pas dans le fichier écrit par l'installeur, car une installation cliente en a rarement besoin.

N'y touchez pas. Elles existent dans le programme, mais une installation cliente n'en a aucun usage :

Les sauvegardes n'ont aucune variable : la sauvegarde automatique se règle dans le tableau de bord, sous Paramètres > Sauvegarde et export. Voir Sauvegarde.

Deux règles s'appliquent à toutes les variables :

• Une valeur vide compte comme absente : la valeur par défaut s'applique.
• Une valeur invalide arrête la passerelle au démarrage, avec un message qui nomme la variable, plutôt que de tourner sur une valeur que vous n'avez pas choisie. Voir la section suivante.

Quand la passerelle refuse de démarrer

Le message se trouve dans sms-gateway logs, sur une ligne contenant gateway stopped. La passerelle redémarre en boucle jusqu'à ce que la cause soit corrigée.

Pourquoi une adresse en http:// simple est refusée : en HTTP, la session du tableau de bord circulerait en clair sur internet. Seul un nom .local (mode réseau local) ou localhost est accepté sans HTTPS.

Pourquoi le mode carrier est refusé sans table : il n'acheminerait rien par opérateur, et vous croiriez payer le tarif intra-réseau alors que vous paieriez le tarif inter-réseaux.

Une restauration qui échoue (voir Sauvegarde et restauration) n'empêche jamais le démarrage : la passerelle démarre sur la base dont elle dispose, et journalise l'erreur.

La clé maîtresse

Au premier démarrage, la passerelle crée une clé maîtresse, secret.key, dans son dossier de données. Elle protège les secrets des téléphones appairés, les secrets des webhooks et votre clé de licence enregistrée dans la base, et elle identifie votre machine auprès de notre serveur de licences (seule une empreinte dérivée est envoyée, jamais la clé).

La perdre oblige à appairer de nouveau chaque téléphone et à saisir de nouveau la clé de licence. Elle vit à côté de la base, pas dedans : un export de la base seul ne la contient pas, alors que l'archive sms-gateway backup, qui copie tout le dossier de données, la contient.

Ce que contient le dossier de données

Le conteneur est verrouillé : il ne peut écrire nulle part ailleurs que dans ce dossier et dans un espace temporaire utilisé pour les exports de la base. Si vous remplacez le docker-compose.yml fourni par votre propre configuration, gardez la ligne hostname: sms-gateway (sans elle, chaque recréation du conteneur ressemble à un déménagement pour notre serveur de licences) et le montage /tmp (sans lui, l'export de la base échoue).

Sauvegarde

Toute l'installation vit dans le dossier de données. La sauvegarde la plus simple est :

sudo sms-gateway backup

Lancée depuis le dossier où vous voulez l'archive, elle arrête la passerelle le temps de la copie, quelques secondes (les téléphones gardent leurs messages pendant ce temps), écrit sms-gateway-backup-<date>.tar.gz dans le dossier courant, puis la redémarre et attend qu'elle réponde. Cette archive contient la clé maîtresse avec la base : rangez-la comme le document le plus sensible de l'installation, et pas sur la même machine.

La passerelle se sauvegarde aussi automatiquement, sans interrompre les envois : chaque jour à 03:00 dans le fuseau de la plateforme par défaut, sept copies conservées, dans le dossier de données. Changez l'heure, la fréquence et le nombre de copies, ou désactivez-la, dans Paramètres > Sauvegarde et export, qui liste et restaure aussi les sauvegardes et exporte vos données en CSV ou JSON. Ces copies restent sur la machine : téléchargez-en une, ou copiez une archive de sms-gateway backup, pour garder une copie ailleurs.

Tout est détaillé dans Sauvegarde et restauration.

Les guides d'hébergement

Cette page couvre l'installation elle-même. Ce qui est propre à chaque type de machine a son propre guide :

Et ensuite