Installing on a VPS

This guide installs the gateway on a server rented from a hosting provider, such as Hetzner Cloud, OVH or DigitalOcean. It assumes a fresh machine running Debian 12, or Ubuntu 22.04 or later, and SSH access with sudo.

At the end, the gateway is reachable over HTTPS on your own domain name, restarts on its own after a reboot, and phones can pair from any network, 4G included.

In short, once the DNS is set up and ports 80 and 443 are open:

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

The rest of this page covers what is specific to a VPS. The full path (purchase, key, first account, activation, pairing) is in Installation.

1. Choose the plan

The smallest plan of your hosting provider is enough to start. Nothing is compiled on the server: the gateway is downloaded ready to run.

Resource	What to know
Memory	The gateway uses very little. The HTTPS server next to it adds a little more
Processor	x86 (`amd64`) and ARM (`arm64`) plans both work
Disk	The database grows with your message history. A few gigabytes cover a long history; keep room for backups
Other	No database server, no cache, no third-party service to rent

2. The domain name

Create an A record pointing at the IP address of the VPS (and an AAAA record if you also use IPv6). A dedicated subdomain, for example sms.your-company.com, is the simplest.

Wait until it resolves before installing:

dig +short sms.example.com

The answer must be the IP address of the VPS. The installation script runs the same check and warns you if it differs; the certificate is obtained automatically as soon as the DNS is right.

If the domain is behind a proxy such as Cloudflare, disable the proxy (DNS only) while the certificate is obtained.

3. The firewall

Three open ports, and no more:

Port	Why it is open
22	Your SSH access. Close it and you lose access to the machine
80	Obtaining and renewing the certificate, and redirecting visitors to HTTPS
443	Everything else: dashboard, API, and the connection of the phones

With ufw:

sudo apt install -y ufw
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Do not open port 8080. In domain mode, the gateway only listens on the machine itself; only the HTTPS server is exposed.

Port 80 must stay reachable from the internet, even if all your useful traffic goes over HTTPS: it is used to prove you own the domain.

If your hosting provider has its own firewall (Hetzner Cloud firewall, OVH network firewall, DigitalOcean Cloud Firewall), it applies on top of ufw: open the same three ports there too.

Good to know: Docker publishes ports 80 and 443 through its own rules, which take effect even if ufw does not list them. That is expected for those two ports, and it is why the gateway itself is only published on the machine's internal address.

4. Install

Connect over SSH, then:

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

Part of the command	Default without it	Effect
`--domain <name>`	the script asks for the mode	HTTPS on that name, phones reachable from anywhere
`--yes`	the script asks before each step	Installs Docker without asking if it is missing, and continues past warnings (DNS, busy ports). Remove it to confirm each step yourself

The other options (--port, --dir, --version, --no-docker-install) and their defaults are in Installation, the options.

The script writes the configuration to /opt/sms-gateway/.env, including the public address https://sms.example.com that the pairing QR codes will give the phones. You have nothing to add.

5. Check

sms-gateway status
sms-gateway url
curl -fsS https://sms.example.com/health
curl -fsS https://sms.example.com/ready

Address	Expected answer	What it proves
`/health`	`{"status":"ok","version":"..."}`	The gateway is running, and shows its version
`/ready`	`{"status":"ready","schemaVersion":N}`	The database is open and up to date

Then open https://sms.example.com in your browser: create the first account with the setup code shown by the script (sms-gateway setup-code shows it again), sign in, and paste the license key. The next steps are in Installation, step 4.

If the browser reports an invalid certificate, it has not been obtained yet. The logs of the HTTPS server say why:

sms-gateway logs caddy

The two usual causes are a DNS not propagated yet and port 80 closed at the hosting provider.

6. Automatic startup

Nothing to do: both levels are in place after the installation.

Docker starts with the machine. Check it with sudo systemctl is-enabled docker (answer: enabled).
The gateway restarts on its own after a crash or a reboot, unless you stopped it yourself with sms-gateway stop (then sms-gateway start brings it back).

Check it for real once:

sudo reboot

Reconnect a minute later and run sms-gateway status.

7. If the VPS already runs a web server

If Apache, Nginx or a hosting panel already uses ports 80 and 443, the script warns you: the built-in HTTPS server cannot start next to it. Two ways out:

A machine dedicated to the gateway: the solution without surprises, and the only one the installer supports.
Put the gateway behind your own web server, on your own responsibility:
1. Install with --lan, which leaves the built-in HTTPS server off (add --port <n> if 8080 is already taken; the steps below then use that port).
2. In /opt/sms-gateway/.env, set GATEWAY_BIND=127.0.0.1 (so the gateway is not exposed in plain HTTP), GATEWAY_PUBLIC_URL=https://sms.example.com (the HTTPS address served by your web server) and GATEWAY_INSECURE_COOKIES=false, then sms-gateway restart.
3. Configure your web server to forward https://sms.example.com to http://127.0.0.1:8080, with two requirements: the live stream /events must not be buffered, and the phone connection /ws/device is a WebSocket, which your server must let through (the Upgrade and Connection headers).
4. Set GATEWAY_TRUSTED_PROXIES in .env to the address from which the gateway sees your web server. Without it, every visitor seems to come from the same address, and they all share the same sign-in lockouts and rate limits.
Do not run the installer again with --lan afterwards: it would rewrite the address to the .local form. Updates with sms-gateway update keep your settings.

8. Back up off the machine

The whole installation lives in its data folder: the database, the master key and the backups made from the dashboard. sms-gateway backup writes an archive of it to the current folder, stopping the gateway for the few seconds of the copy.

The gateway also backs up its database automatically, every day at 03:00 in the platform time zone, seven copies kept (Settings > Backup and export). Those copies stay in the data folder, on the same disk.

Copy a backup off the machine (another server, object storage) regularly: a backup that stays on the disk it protects does not survive the loss of that disk. Download an automatic backup from the dashboard, or run sms-gateway backup and copy the archive; delete old archives from time to time, since the command keeps them all. See Backup and restore.

Two warnings that matter. The archive contains the master key and the database: whoever holds it holds everything. Encrypt it before sending it elsewhere. Details in Backup and restore.

9. VPS or Oracle Cloud

Topic	Rented VPS	Oracle Cloud Always Free
Cost	Billed monthly	Free
Processor	Usually `amd64`	`arm64` on Ampere A1 instances. Both work
Firewall	`ufw` on the machine, sometimes a provider firewall too	Oracle's network filtering and the instance firewall
Resources	What you pay for, and can grow	A fixed ceiling
Reclaiming	Never, as long as you pay	Oracle may reclaim an instance it considers idle

See Oracle Cloud Always Free.

You want to	Go to
The full path	Installation
Back up and restore	Backup and restore
Move to another server	Migrating to another server
Know what protects your data	Security