campaign_connector/docs/deployment/deployment-guide.md

SMS Campaign Manager - Deployment Guide

Quick Deployment Summary

This guide provides a streamlined deployment process for the SMS Campaign Manager using Tailscale for reliable connectivity.

Prerequisites Checklist

• Docker & Docker Compose installed on Ubuntu homelab
• Tailscale installed on Ubuntu homelab
• Tailscale installed on Android device
• Termux installed on Android (from F-Droid)
• Termux:API installed on Android (from F-Droid)
• SSH server running in Termux
• SMS permissions granted to Termux:API

Step-by-Step Deployment

1. Prepare Android Device

Install Tailscale:

1. Install Tailscale from Google Play Store
2. Sign in and connect to your Tailnet
3. Note your Android's Tailscale IP (Settings → Connected)
   Example: 100.107.173.66

Install Termux:

1. Download Termux from F-Droid: https://f-droid.org/packages/com.termux/
2. Download Termux:API from F-Droid: https://f-droid.org/packages/com.termux.api/
3. DO NOT use Google Play versions - they're outdated

Setup Termux:

# In Termux on Android, run:
pkg update && pkg upgrade
pkg install openssh termux-api python
sshd
passwd

Grant Permissions:

1. Open Android Settings
2. Navigate to Apps → Termux:API
3. Grant SMS permission
4. Grant Phone permission

2. Configure Ubuntu Homelab

Create .env file:

cd /mnt/storagessd1tb/campaign_connector

cat > .env << 'EOF'
# Android Device Configuration
PHONE_IP=100.107.173.66          # Your Android's Tailscale IP
ADB_PORT=5555
TERMUX_API_PORT=5001

# Flask Application
FLASK_ENV=production
SECRET_KEY=change-this-to-secure-random-string
DEFAULT_DELAY_SECONDS=3

# SMS Retry Configuration
SMS_MAX_RETRIES=3
SMS_RETRY_BASE_DELAY=2
SMS_MAX_RETRY_DELAY=8
EOF

# Edit with your actual Tailscale IP
nano .env

3. Deploy Services

Deploy to Android:

./scripts/deploy-android.sh

This will:

• Test connectivity
• Deploy shell scripts to ~/bin/
• Deploy Python apps to ~/projects/sms-campaign-manager/
• Start all services
• Verify deployment

Start Ubuntu Homelab:

./run.sh start
# OR
docker compose up -d

4. Verify Deployment

Check service health:

# Test Ubuntu homelab
curl http://localhost:5000/health

# Test Android SMS API (replace with your Tailscale IP)
curl http://100.107.173.66:5001/health

# Test Android monitor
curl http://100.107.173.66:5000/

View logs:

# Ubuntu homelab logs
docker compose logs -f sms-campaign

# Android service logs
ssh -p 8022 100.107.173.66 "tail -f ~/logs/sms-api.log"

Service URLs

After successful deployment:

• Ubuntu Campaign Manager: http://localhost:5000
• Android SMS API: http://100.107.173.66:5001
• Android Monitor: http://100.107.173.66:5000

Managing Services

Ubuntu Homelab

./run.sh start     # Start services
./run.sh stop      # Stop services
./run.sh logs      # View logs
./run.sh status    # Check status
./run.sh rebuild   # Rebuild and restart

Android Services

# SSH into Android (replace with your Tailscale IP)
ssh -p 8022 100.107.173.66

# Start all services
~/bin/start-all-services.sh

# Check status
~/bin/sms-service.sh status

# View logs
tail -f ~/logs/sms-api.log
tail -f ~/logs/monitoring.log

Connection Architecture

Ubuntu Homelab
    ↓ (Tailscale VPN)
Android Device
    ↓
Termux API Server (Port 5001) ← Primary SMS method
    ↓
Native Android SMS API

Advantages:

• Works anywhere (not limited to same WiFi)
• Encrypted connection via Tailscale
• Faster SMS sending (direct API vs ADB)
• No ADB timeouts or connection issues
• Automatic failover to ADB if Termux fails

Troubleshooting

"Cannot reach Android device"

# Check Tailscale status
tailscale status

# Ping Android device
ping 100.107.173.66

# Verify Tailscale IP in .env matches Android

"SSH connection failed"

# Check if SSH server is running on Android
ssh -p 8022 100.107.173.66 "whoami"

# Restart SSH server in Termux
sshd

"Termux API not responding"

# Redeploy services
./scripts/deploy-android.sh

# Or manually restart
ssh -p 8022 100.107.173.66 "~/bin/start-all-services.sh"

# Check if services are running
ssh -p 8022 100.107.173.66 "ps aux | grep python"

"Permission denied" when sending SMS

1. Open Android Settings
2. Apps → Termux:API
3. Permissions → SMS → Allow
4. Restart Termux API service

Next Steps

After deployment:

1. Access web interface: http://localhost:5000
2. Upload a CSV with contacts
3. Create a campaign
4. Send test SMS
5. Monitor delivery status

Support

For issues or questions:

• Check logs: docker compose logs -f
• Verify all prerequisites are met
• Ensure Tailscale is running on both devices

Related Documentation

• Installation Guide - Complete setup instructions
• Quick Start - Rapid deployment
• Security Setup - Security configuration
• Troubleshooting - Common issues
• Testing Guide - Verification procedures