Getting Started 🚀

Private Server 🔒

To enhance privacy and control, you can host your own private server. This keeps all message data within your infrastructure while maintaining push notification capabilities through our public server at api.sms-gate.app. This setup eliminates the need to configure Firebase Cloud Messaging (FCM) or rebuild the Android app, but it does demand some technical know-how.

flowchart
    %% === MAIN BLOCKS ===
    Users["👥 Users"]
    Android["🤖 SMSGate App"]

    subgraph PrivateServer["Private Server"]
        GoServerPrivate["🐹 Server"]
        GoWorkerPrivate["🐹 Worker"]
        DB["🦭 DB"]

        GoServerPrivate <--> DB
        GoWorkerPrivate --> DB
    end

    subgraph Google["Google"]
        FCM["🔥 FCM"]
    end

    subgraph PublicServer["Public Server"]
        GoServerPublic["🐹 api.sms-gate.app"]
    end

    %% === CONNECTIONS ===

    Users -->|REST API| GoServerPrivate
    GoServerPrivate -->|notification| GoServerPublic
    GoServerPublic -->|notification| FCM
    FCM -->|PUSH| Android
    Android <--> GoServerPrivate

    %% === ALTERNATIVE NOTIFICATION PATH ===
    Android -.->|SSE| GoServerPrivate

    %% === STYLING ===
    classDef altConn stroke-dasharray: 5 5,stroke:#888,fill:none;
    class Android,GoServerPrivate,GoWorkerPrivate,DB altConn;

Prerequisites ✅

The easiest way to run the server is to use Docker. For alternative installation methods, see Private Server Documentation.

To run the server, you'll need:

• 🐧 Linux VPS
• 🐳 Docker installed
• 🗄️ MySQL/MariaDB server with empty database and privileged user
• 🔄 Reverse proxy with valid SSL certificate (project CA supported)

Run the Server 🖥️

1. Create configuration
   Copy the example config and customize:

   Get config.yml template

   wget https://raw.githubusercontent.com/android-sms-gateway/server/master/configs/config.example.yml -O config.yml
   

   Key sections to edit:
   Private Server Configuration Example

   gateway:
       mode: private
       private_token: your-secure-token-here # (1)!
   http:
       listen: 0.0.0.0:3000
   database: # (2)!
       host: localhost
       port: 3306
       user: root
       password: root
       database: sms
       timezone: UTC
   

   1. Must match device configuration
   2. Must match MySQL/MariaDB configuration

   Configuration Location

   By default, the application looks for config.yml in the current working directory. Alternatively, you can set the CONFIG_PATH environment variable to specify a custom path to the configuration file.

2. Launch the server

   Docker Command

   docker run -d --name sms-gateway \
       -p 3000:3000 \
       -v $(pwd)/config.yml:/app/config.yml \
       ghcr.io/android-sms-gateway/server:latest
   

3. Run the background worker (optional)

   Docker Command

   docker run -d --name sms-gateway-worker \
       -v $(pwd)/config.yml:/app/config.yml \
       ghcr.io/android-sms-gateway/server:latest \
       /app/app worker
   

   The background worker handles maintenance tasks. See Background Worker for setup details.

4. Configure reverse proxy

   Example Nginx Config

   location / {
       proxy_pass http://localhost:3000;
       proxy_set_header Host $host;
       proxy_set_header X-Forwarded-For $remote_addr;
   }
   

   See Reverse Proxy Configuration for setup details and advanced options.

curl https://private.example.com/health
# Should return JSON health status

Configure Android App 📱

1. Access Settings
   Navigate to Settings tab → Cloud Server

2. Enter server details
   

   API URL: https://private.example.com/api/mobile/v1
   Private Token: your-secure-token-here
   

3. Activate connection

   1. Switch to Home tab
   2. Activate Cloud server switch
   3. Restart the app using the bottom button

Username: A1B2C3
Password:  z9y8x7...

Password Management 🔑

Identical to Cloud Server mode.

See Also 📚

• Private Server Documentation
• Ubuntu/Docker/Nginx Setup Guide
• Docker Compose Quickstart