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.

Prerequisites ✅

To run the server, you'll need:

• 🗄️ MySQL/MariaDB server with empty database and privileged user
• 🐧 Linux VPS
• 🔄 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:

   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

   🐳 With Docker🖥️ Without Docker📦 With Helm

   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
   

   1. Build the binary

      git clone https://github.com/android-sms-gateway/server.git
      cd server
      go build -o sms-gateway ./cmd/sms-gateway
      chmod +x sms-gateway
      

   2. Run database migrations

      ./sms-gateway db:migrate up
      

   3. Launch the server

      ./sms-gateway
      

   1. Install Helm
   2. Add the chart repository

      helm repo add sms-gate https://s3.sms-gate.app/charts
      helm repo update
      

   3. Create values.yaml file

      values.yaml

      image:
        pullPolicy: IfNotPresent
      
      database:
        deployInternal: true
        mariadb:
          rootPassword: ${GENERATE_MARIADB_ROOT_PASSWORD}
        password: ${GENERATE_DATABASE_PASSWORD}
      
      gateway:
        privateToken: ${GENERATE_PRIVATE_TOKEN}
      

   4. Install the chart

      helm upgrade --install sms-gate-server sms-gate/server \
          --create-namespace \
          --namespace sms-gate \
          --values values.yaml
      

   Security Warning

   Never commit secrets to version control! Replace placeholder values with actual high-entropy secrets:

   • Generate unique passwords/tokens using: openssl rand -base64 32
   • Use environment variables or secret management tools
   • Consider sealed-secrets for Kubernetes
   • Use cloud secret managers (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager)

   For detailed Helm chart documentation, see Helm Chart Documentation.

3. 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;
   }
   

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 📚

• Ubuntu/Docker/Nginx Setup Guide
• Docker Compose Quickstart