Docker Swarm deployment stack for the SMSGate platform: reverse proxy, database, cache, application services, monitoring, and alerting. This README covers local cluster bring-up only; deep deployment and operations guides live at docs.sms-gate.app.
The platform delivers SMS messages through mobile devices. This repository packages the server-side infrastructure for single- or multi-node deployments:
- Problem: the gateway needs a production-grade runtime - TLS termination, persistent storage, scheduled backups, monitoring, and alerting.
- Solution: four self-contained Docker Swarm stacks, declarative service configuration, and secrets management through Swarm secrets.
- Intended users: operators and developers who deploy or maintain the gateway infrastructure.
Everything here is configuration-as-code: no application source code lives in this repository, only the stacks that run it.
- TLS by default: Traefik v3 terminates HTTPS with Let's Encrypt certificates; the
cloudflarecert resolver uses DNS-01 challenges for SMPPS, SMTPS, and public HTTPS routes. - HTTP, SMTP, and SMPP gateways: traffic routing on ports 80/443, 587/465, and 2775/2776.
- Mobile push: the backend sends Firebase Cloud Messaging (FCM) notifications from a Google service-account credential.
- Rate limiting and access control: per-route rate limits for API and webhook endpoints; basic auth and IP allowlists for dashboards and metrics.
- Scheduled database backups: MariaDB dumps uploaded to S3 on a cron schedule via swarm-cronjob.
- Certificate authority:
ca-backendissues certificates signed by a root CA stored in Swarm secrets. - Monitoring and alerting: Prometheus scrapes labeled services; Alertmanager routes
criticalalerts to Telegram andwarning/infoto email; Grafana for visualization; cAdvisor and node_exporter run globally on every node, the latter exposing host metrics. - Multi-node placement: services pin to labeled nodes (
redis,db,traefik,cronjob,prometheus,grafana,portainer).
Four stacks compose the deployment. The infra stack must be deployed first because app and monitoring consume its internal and public overlay networks, and each references its own external secrets.
| File | Stack | Contents |
|---|---|---|
compose.infra.yml |
infra |
Traefik v3, MariaDB, Redis, phpMyAdmin, Redis Commander, S3 backup job, swarm-cronjob |
compose.app.yml |
app |
Backend API + worker, ca-backend, smpp-server, email-to-sms, webhook-tester, web-dashboard |
compose.monitoring.yml |
monitoring |
Prometheus, Alertmanager, cAdvisor (global), node_exporter (global), Grafana |
compose.portainer.yml |
portainer |
Portainer CE (optional management UI) and its agent |
A full architecture diagram lives in the central docs: https://docs.sms-gate.app/
- Docker Engine with Swarm mode enabled (one or more Linux nodes; the Portainer agent is global on Linux nodes only).
- A public domain with DNS records pointing at the cluster (see Operations for the hostnames to expose).
- A Cloudflare API token with DNS edit permission (used for ACME DNS-01 challenges).
- A terminal on a Swarm manager node.
-
Initialize or join the Swarm (run on the first manager):
docker swarm init
-
Label nodes for service placement. Each service pins to a node label; labels that do not exist simply stay empty until their services are deployed:
docker node update --label-add redis=true <manager-node> docker node update --label-add db=true <db-node> docker node update --label-add traefik=true <manager-node> docker node update --label-add cronjob=true <manager-node> docker node update --label-add prometheus=true <monitoring-node> docker node update --label-add grafana=true <monitoring-node> docker node update --label-add portainer=true <manager-node>
-
Create the external secrets referenced by the stacks (values are operator-provided):
docker secret create mariadb_root_password - docker secret create users.htpasswd - docker secret create root-ca.crt - docker secret create root-ca.key - docker secret create telegram_bot_token - docker secret create email_password - docker secret create grafana_admin_password -
All secrets are declared
external: true, so they must exist before stack deployment. -
Create the environment file from the template and fill in your values:
cp .env.example .env
docker stack deployinterpolates variables from the shell environment, not from.env. Load it into the shell before each deployment (for example,set -a; source .env; set +a). SetROOT_DOMAINbefore deploying: if it is unset, Docker substitutes empty values and public host rules become empty.
Deploy in order: infra first (it creates the internal and public overlay networks), then app and monitoring, optionally followed by portainer.
docker stack deploy -c compose.infra.yml infra
docker stack deploy -c compose.app.yml app
docker stack deploy -c compose.monitoring.yml monitoring
docker stack deploy -c compose.portainer.yml portainerinfracreates theinternal/publicoverlay networks, theredis-data,mariadb-data, andletsencryptvolumes, and starts Traefik, MariaDB, Redis, Redis Commander, phpMyAdmin, and the cron scheduler.appdeploys the backend API, worker, CA backend, SMPP server, email-to-SMS gateway, webhook tester, and web dashboard. Theworkerservice starts with zero replicas; scale it if background tasks are needed.monitoringdeploys Prometheus, Alertmanager, cAdvisor (global), node_exporter (global), and Grafana.portainerdeploys Portainer CE (published on port 9443, constrained to manager nodes) and a global agent on all Linux nodes.
After deployment, every public service is reachable at <subdomain>.<ROOT_DOMAIN>:
| Stack | Subdomain | Service |
|---|---|---|
infra |
admin. |
Traefik dashboard |
infra |
pma. |
phpMyAdmin |
infra |
redis. |
Redis Commander |
infra |
db. |
MariaDB (direct) |
app |
api. (API_SUBDOMAIN) |
Backend API |
app |
ca. |
Certificate authority |
app |
smpp. |
SMPP gateway |
app |
smtp. |
Email-to-SMS gateway |
app |
webhook. |
Webhook tester |
app |
dashboard. |
Web dashboard |
monitoring |
prometheus. |
Prometheus |
monitoring |
alerts. |
Alertmanager |
monitoring |
mon. |
Grafana |
Portainer is not routed through Traefik; it publishes port 9443 directly on manager nodes.
db. exposes the MariaDB wire protocol (TCP 3306) as plain-TCP passthrough; connections are limited to the DB__IP_ALLOWLIST ranges via a Traefik TCP ipAllowList middleware. Point an A record at the manager/traefik node (do not proxy through Cloudflare, so client IPs stay visible to the allowlist), restrict port 3306 in the node firewall to the allowed ranges, and use a MariaDB user that permits remote login. Note read_only=ON from mariadb/51-replication.cnf makes remote sessions read-only unless the user has the SUPER privilege.
Compose configs are versioned with STACK_VERSION. After editing a config file, bump STACK_VERSION in .env and re-deploy the stack that consumes it:
- Traefik (
traefik/traefik.yml,traefik/dynamic.yml) and MariaDB configs ->infra - Backend (
backend/config.yml) ->app - Prometheus and Alertmanager configs ->
monitoring
db-backupruns on theDB_BACKUP__SCHEDULEcron (default@daily) and uploads a MariaDB dump toDB_BACKUP__STORAGE_URL; it runs as a cron job, sodocker service psshows no running tasks between runs.- Services labeled
prometheus.io/scrape=truepublish Prometheus metrics; scrape targets are discovered via those labels on theinternalnetwork. - The full environment reference (every
__-separated variable in .env.example).
- Fork the repository and create a feature branch.
- Keep changes scoped to a single concern (a compose file, a config file, or docs).
- Open a pull request with a clear description of the change and any verification performed.
- Add the
readylabel once the PR passes review, anddeployedonce the change is live.
Note the automation in .github/workflows/:
close-issues-prs.ymlmarks issues/PRs stale after 7 days of inactivity and closes them after 7 more days; assigned items are exempt.pr-labels.ymlremoves thereadyanddeployedlabels whenever new commits are pushed to a PR.
Apache-2.0. See LICENSE.