Installation Guide

This guide walks you through deploying the SMS Gateway Proxy platform. The recommended deployment method is Docker Compose, which orchestrates all required services in containers.

Prerequisites

Before you begin, ensure the following requirements are met:

System Requirements

Platform Components

The platform consists of four containerized services:

Application Directory Structure

The proxy application expects the following directory layout on the host. All paths are relative to the application root and must be mounted as persistent volumes into the container.

.
├── config
│   ├── config_local.yaml
│   ├── config_test.yaml
│   ├── dryrunctr
│   └── dryrunctr.tmp
├── journal
│   └── stat
├── license
│   ├── license_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.lic
│   ├── proxy.lic
│   └── registry.json
├── logs
├── smpp_rules
│   ├── routes.ini
│   └── smpp_rules.toml
├── storage
│   ├── sso.db
│   ├── sso.db-shm
│   └── sso.db-wal

Directory Descriptions

Quick Start

1. Create a project directory

mkdir sms-gateway && cd sms-gateway

2. Prepare the directory structure

Create all required directories and place your configuration and license files:

mkdir -p config journal/stat license logs smpp_rules storage

Copy your files into the appropriate directories:

# Application configuration
cp config_local.yaml config/

# License files (provided by vendor)
cp *.lic license/

# SMPP configuration
cp smpp_rules.toml smpp_rules/

3. Create the SMPP configuration

If you don't have an smpp_rules.toml yet, create smpp_rules/smpp_rules.toml with your SMPP connection parameters:

[links.100]
esme_disabled = false
esme_addr = "smsc.your-provider.com"
esme_port = 2775
esme_systemid = "your_system_id"
esme_password = "your_password"
esme_rate = 100
esme_rate_burst = 100
esme_enquirelink = 15
esme_enquirelink_timeout = 40
esme_resp_timeout = 20

For a complete reference of all configuration parameters, see the Configuration Reference.

4. Create the Docker Compose file

Create docker-compose.yml:

version: "3.8"

services:
  proxy:
    image: sms-sender-proxy:v1.0.0
    ports:
      - "8080:8080"     # REST API
      - "44044:44044"   # gRPC API
    volumes:
      - ./config:/app/config
      - ./journal:/app/journal
      - ./license:/app/license
      - ./logs:/app/logs
      - ./smpp_rules:/app/smpp_rules
      - ./storage:/app/storage
    depends_on:
      - redis
      - aerospike
    restart: unless-stopped

  redis:
    image: redis:latest
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    restart: unless-stopped

  aerospike:
    image: aerospike:ce-6.4.0
    ports:
      - "3000:3000"
    volumes:
      - aerospike-data:/opt/aerospike/data
    restart: unless-stopped

volumes:
  redis-data:
  aerospike-data:

Volume Mapping Reference

All proxy volumes are bind mounts from the host directory to the container path under /app/:

5. Start the services

docker compose up -d

6. Verify the deployment

Check that all services are running:

docker compose ps

Verify the proxy health endpoint:

curl http://localhost:8080/healthy

Expected response:

{ "status": "ok" }

Check Prometheus metrics are available:

curl http://localhost:8080/metrics

Post-Installation Steps

Register the first user

Create an admin user via the REST API:

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "your-secure-password",
    "app_name": "my-gateway"
  }'

Verify SMPP connectivity

Check the status of configured SMPP links:

curl http://localhost:8080/api/v1/dashboard/smpp-links

Send a test message

Once a user is registered and SMPP links are connected, send a test SMS:

curl -X POST http://localhost:8080/api/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "esme": 100,
    "source_addr": "TestSender",
    "destination_addr": "380501234567",
    "short_message": "Hello from SMS Gateway!"
  }'

Network Configuration

The proxy requires outbound network access to SMSC endpoints on the ports configured in smpp_rules.toml. Ensure that your firewall rules allow the following:

Backup and Recovery

Because all application state is stored in the host-mounted directories, backup is straightforward:

# Stop the proxy to ensure consistent state
docker compose stop proxy

# Archive all persistent data
tar czf sms-gateway-backup-$(date +%Y%m%d).tar.gz \
  config/ journal/ license/ logs/ smpp_rules/ storage/

# Restart
docker compose start proxy

Critical directories to back up:

• license/ — license re-activation may be required if lost
• storage/ — contains the user database; loss means all users must re-register
• config/ — all application tuning and behavior settings
• smpp_rules/ — SMPP connection definitions

Upgrading

To upgrade the platform to a new version:

1. Pull the new proxy image
2. Update the image tag in docker-compose.yml
3. Restart the service:

docker compose pull proxy
docker compose up -d proxy

The proxy supports rolling restarts — active SMPP connections will be re-established automatically after the container starts.

Next Steps

• Configuration Reference — detailed application, SMPP link, and pool parameters
• Deploy MCP — set up contact policy filtering
• Infrastructure — architecture overview of platform components
• REST API — complete API reference for integration