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:**
```bash
# 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:**
```bash
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:**
```bash
./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:**
```bash
./run.sh start
# OR
docker compose up -d
```

### 4. Verify Deployment

**Check service health:**
```bash
# 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:**
```bash
# 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

```bash
./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

```bash
# 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"
```bash
# Check Tailscale status
tailscale status

# Ping Android device
ping 100.107.173.66

# Verify Tailscale IP in .env matches Android
```

### "SSH connection failed"
```bash
# 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"
```bash
# 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](../setup/installation.md) - Complete setup instructions
- [Quick Start](../setup/quick-start.md) - Rapid deployment
- [Security Setup](../security/security-setup.md) - Security configuration
- [Troubleshooting](../guides/troubleshooting.md) - Common issues
- [Testing Guide](../guides/testing.md) - Verification procedures