Migrating to another server

This guide moves an existing installation to another machine: changing hosting provider, going from a local server to a VPS, replacing a machine at the end of its life. Every step says what you should see, and why it matters.

The one thing to remember. Take the whole data folder with you, master key included. Then the license has nothing to reactivate, the phones reconnect by themselves if the address does not change, and the migration costs a few minutes. Without the master key, it still works, but every phone must be paired again and the license key entered again.

1. What decides how smooth the migration is

Two things, and only two:

The IP address, the hardware, the operating system and the hosting provider play no part. With the provided installation, the machine identity seen by our license server follows the master key: take it along, and for us it is the same machine.

2. What never breaks

• Your service does not stop because of the license. Our license server being unreachable, or seeing a new machine, never suspends sending. At worst, the License screen shows a renewal pending. Only a license withdrawn by us (for example after a refund) suspends sending.
• After twelve months of ownership, the license no longer needs to contact us at all.
• Your data stays readable and exportable in every case.

3. Before you start

4. Route A: move the full archive (recommended)

This route keeps everything: history, accounts, settings, phones, license.

Step 1: back up, then stop the old gateway

On the old machine:

sudo sms-gateway backup
sudo sms-gateway stop

backup writes sms-gateway-backup-<date>.tar.gz to the current folder; stop then stops the gateway for good, so that nothing new is written on the old machine after the copy. While no gateway answers, phones keep outgoing and incoming messages in their queue.

Check that the archive contains the master key:

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

If secret.key is not listed, stop: you would be on route B without knowing it.

On Windows, see Backup and restore for the equivalent commands.

Step 2: copy the archive to the new machine

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

The archive contains all your data and the master key: transfer it only over an encrypted channel (scp, sftp), and delete the copies once the migration is checked.

Step 3: point the domain at the new machine (domain mode)

Change the A record of your domain to the IP address of the new machine. Keep the same domain: the phones will find the new machine by themselves.

Step 4: install the gateway on the new machine

Run the usual installation, with the same mode as before:

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

(or --lan for a local server; in that case, give the new machine the same name as the old one, see Local server).

Do not create an account on the screen that appears: your accounts come back with the archive. If the DNS has not switched yet, the script warns you; the certificate is obtained automatically once it has.

Step 5: put the archive in place

On the new machine, in the folder where the archive is:

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

This replaces the empty data of the fresh installation with yours, master key included. If the volume name is different on your machine (older installation), find it with docker volume ls --filter label=com.docker.compose.volume=gateway-data.

Step 6: check

Go through section 8. Phones reconnect within a minute or two, and hand over the messages they kept.

5. Route B: only a database copy

Use this route when the old machine is lost and you only have a database copy: a backup downloaded from Settings > Backup and export, or a .db file. It brings back your history, contacts and settings, but not the master key.

1. Install the gateway on the new machine (same or newer version than the copy), in the mode you want. You can create the first account: the copy will replace it.
2. Put the copy in the backups folder and restore it, as described in Restore a copy made on another machine, then restart with sudo sms-gateway restart. Sign in with the accounts of the copy.
3. The license: the old machine still holds it, so entering your key directly is refused with a message saying the key is already in use on another machine (the dashboard may title it as a withdrawn key: it is not, and nothing is suspended). Free it first: in your customer area, click Regenerate key. This detaches every machine from the license and gives you a new key. Enter that new key in License.
4. Pair every phone again (section 7).
5. Webhooks: their secrets can no longer be read. Give each webhook a new secret through the API (PATCH /api/v1/webhooks/{id} with a new secret) and update it on the receiving side. See Webhooks.

If you do still have the old secret.key, you can avoid steps 3 to 5: use route A's step 5 with a full archive, or ask us for help.

6. The license after the move

With route A, there is nothing to do: the new machine presents the same identity as the old one. The License screen shows Licence active.

If the license sees a new machine (route B, or a customized installation that changed the container name or data folder), here is what you see, and none of it stops sending:

The Check log shows these attempts with a signed refusal for a different machine. To solve it, free the license with Regenerate key in your customer area, then enter the new key in License, and click Check now. Details in License.

Do this at the end of the migration, once you are sure you keep the new machine: regenerating the key also prevents the old machine from renewing, which makes rolling back more work.

7. The paired phones

A phone remembers the address of its QR code, its identity and its secret. The gateway cannot push a new address to it.

To pair a phone again:

1. Let it hand over its pending messages first if it can still reach a gateway: Unpair deletes the messages still queued on the phone.
2. In the app, Unpair, then confirm.
3. In the dashboard, Devices > Pair a device, and scan the new QR code (valid five minutes).

Then check the daily quota and settings of each SIM in Devices: see Devices.

If a phone does not reconnect although nothing should have changed, first check the address: open https://<your address>/health in the phone's browser. Only then consider pairing again.

8. Check after the migration

Do not dismantle the old machine before every line is checked. As long as it exists, rolling back takes a minute.

Once everything is checked:

• On the old machine, sudo sms-gateway uninstall --purge deletes the gateway and its data. Only do it when you are sure: it cannot be undone.
• Delete the transferred archive copies, or store them encrypted with your backups.
• After a route B restore, the database set aside as gateway.db.pre-restore-... can be deleted (see Backup and restore).
• Schedule backups on the new machine: see Backup and restore.

9. Roll back

10. When the new gateway does not start

sms-gateway logs shows the reason on a line containing gateway stopped. After a migration, the usual causes are:

The full list of startup messages is in Installation.

Settings to carry over by hand: anything you changed or uncommented in the .env file of the old 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...). An installation older than this version may also have variables added by hand to its docker-compose.yml: move them to the new .env. Everything set in the dashboard, the automatic backup schedule included, travels with the data.