2025-12-30 08:50:08 -07:00

4.8 KiB

Raw Blame History

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:

./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
./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:

Access web interface: http://localhost:5000
Upload a CSV with contacts
Create a campaign
Send test SMS
Monitor delivery status

Support

For issues or questions:

Check logs: docker compose logs -f
Review README.md for detailed documentation
Verify all prerequisites are met
Ensure Tailscale is running on both devices

4.8 KiB Raw Blame History