campaign_connector/docs/setup/installation.md

# Installation Guide

This guide walks through the complete installation of SMS Campaign Manager for production use.

## Overview

The installation process involves:

1. Setting up the Ubuntu server with Docker
2. Configuring the Android device with Termux
3. Establishing connectivity between devices
4. Deploying the application

## Prerequisites

### Ubuntu Server

- Ubuntu 20.04 or later
- Docker and Docker Compose installed
- At least 1GB RAM and 10GB disk space
- Network access to Android device

### Android Device

- Android 7.0 or later
- Termux app (from F-Droid)
- Termux:API app (from F-Droid)
- Active SIM card for SMS

### Network

Choose one of:
- **Tailscale (Recommended)**: Secure connectivity anywhere
- **Local Network**: Both devices on same WiFi

## Step 1: Install Docker on Ubuntu

If Docker is not installed:

```bash
# Update package index
sudo apt update

# Install prerequisites
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# Add Docker's GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add user to docker group
sudo usermod -aG docker $USER

# Apply group changes (or log out and back in)
newgrp docker

# Verify installation
docker --version
docker compose version
```

## Step 2: Install Tailscale (Recommended)

On Ubuntu:

```bash
# Install Tailscale
curl -fsSL https://tailscale.com/install.sh | sh

# Connect to your Tailnet
sudo tailscale up

# Note your Tailscale IP
tailscale ip -4
```

On Android:
1. Install Tailscale from Google Play Store
2. Open Tailscale and sign in with the same account
3. Enable the VPN connection
4. Note your Android's Tailscale IP (Settings → Connected)

## Step 3: Set Up Android Device

### Install Termux

Download from F-Droid (not Google Play):
- [Termux](https://f-droid.org/packages/com.termux/)
- [Termux:API](https://f-droid.org/packages/com.termux.api/)

### Configure Termux

Open Termux and run:

```bash
# Update packages
pkg update && pkg upgrade -y

# Install required packages
pkg install -y openssh python termux-api

# Start SSH server
sshd

# Set SSH password
passwd
# Enter a secure password when prompted

# Verify SSH is running
pgrep sshd
```

### Grant Permissions

On Android:
1. Open Settings → Apps → Termux:API
2. Tap Permissions
3. Enable SMS permission
4. Enable Phone permission (optional, for call info)

### Test Termux API

In Termux:

```bash
# Test SMS access
termux-sms-list -l 1

# Should display recent SMS (if any)
```

## Step 4: Clone the Repository

On Ubuntu:

```bash
# Clone or download the project
cd /path/to/your/projects
git clone <repository-url> campaign_connector
cd campaign_connector
```

Or if you have the files:

```bash
cd /mnt/storagessd1tb/campaign_connector
```

## Step 5: Configure Environment

Create your `.env` file:

```bash
# Copy the example file
cp .env.example .env

# Edit configuration
nano .env
```

Set these required values:

```env
# Android Device (use your Tailscale IP)
PHONE_IP=100.x.x.x
ADB_PORT=5555
TERMUX_API_PORT=5001

# Flask Application
FLASK_ENV=production
DEFAULT_DELAY_SECONDS=3

# SMS Configuration
SMS_MAX_RETRIES=3
SMS_RETRY_BASE_DELAY=2
SMS_MAX_RETRY_DELAY=8
```

## Step 6: Generate API Keys

Generate secure API keys:

```bash
python3 src/core/auth.py
```

Add the generated keys to your `.env`:

```env
# API Keys (paste generated values)
ADMIN_API_KEY=<generated-admin-key>
USER_API_KEY=<generated-user-key>
TERMUX_API_KEY=<generated-termux-key>
SECRET_KEY=<generated-secret-key>
TERMUX_API_SECRET=<same-as-termux-api-key>

# User Management
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!
```

Secure the file:

```bash
chmod 600 .env
```

## Step 7: Deploy to Android

Test connectivity:

```bash
# Test SSH connection
ssh -p 8022 android-dev@YOUR_ANDROID_IP "echo 'Connection successful'"
```

Run the deployment script:

```bash
./scripts/deploy-android.sh
```

This script:
- Tests connectivity
- Creates required directories on Android
- Deploys Python scripts and services
- Starts the Termux API server
- Verifies deployment

If the script fails, you can deploy manually:

```bash
# Copy files to Android
scp -P 8022 android/*.py android-dev@YOUR_ANDROID_IP:~/projects/sms-campaign-manager/
scp -P 8022 android/*.sh android-dev@YOUR_ANDROID_IP:~/bin/

# Set permissions
ssh -p 8022 android-dev@YOUR_ANDROID_IP "chmod +x ~/bin/*.sh"
```

## Step 8: Configure Android API Key

SSH into Android:

```bash
ssh -p 8022 android-dev@YOUR_ANDROID_IP
```

Set the API key:

```bash
# Set API key (use the same TERMUX_API_KEY from Step 6)
echo 'export SMS_API_SECRET="<your-termux-api-key>"' >> ~/.bashrc
source ~/.bashrc

# Verify it's set
echo $SMS_API_SECRET
```

## Step 9: Start Services

### Start Android Services

On Android (via SSH or Termux directly):

```bash
~/bin/start-all-services.sh
```

Or start individually:

```bash
# Start SMS API server
python ~/projects/sms-campaign-manager/android/termux-sms-api-server.py &

# Check if running
curl http://localhost:5001/health
```

### Start Ubuntu Application

```bash
# Build and start Docker container
docker compose up -d

# View logs
docker compose logs -f sms-campaign

# Press Ctrl+C to stop viewing logs
```

## Step 10: Verify Installation

### Check Service Health

```bash
# Test Ubuntu application
curl http://localhost:5000/health
# Expected: {"status": "ok", "version": "2.0"}

# Test Android Termux API
curl http://YOUR_ANDROID_IP:5001/health
# Expected: {"status": "healthy", ...}
```

### Test Authentication

```bash
# Should fail (no API key)
curl http://localhost:5000/api/campaign/list

# Should succeed
curl -H "X-API-Key: YOUR_USER_API_KEY" http://localhost:5000/api/campaign/list
```

### Access Web Dashboard

Open browser: `http://localhost:5000`

Log in with:
- Username: `admin`
- Password: (from ADMIN_PASSWORD in .env)

## Verification Checklist

After installation, verify:

- [ ] Docker container running: `docker compose ps`
- [ ] Ubuntu health check passes: `curl http://localhost:5000/health`
- [ ] Android health check passes: `curl http://YOUR_ANDROID_IP:5001/health`
- [ ] Web login works at `/login`
- [ ] API authentication enforced
- [ ] Container not in privileged mode: `docker inspect sms-campaign-manager | grep Privileged`

## Troubleshooting

### Can't Connect to Android

```bash
# Check Tailscale is running
tailscale status

# Ping Android device
ping YOUR_ANDROID_IP

# Test SSH
ssh -p 8022 android-dev@YOUR_ANDROID_IP "whoami"
```

### Docker Won't Start

```bash
# Check logs
docker compose logs sms-campaign

# Rebuild container
docker compose down
docker compose build --no-cache
docker compose up -d
```

### Android Server Not Responding

```bash
# SSH to Android
ssh -p 8022 android-dev@YOUR_ANDROID_IP

# Check if server is running
ps aux | grep termux-sms-api-server

# Check logs
tail -20 ~/logs/sms-api.log

# Restart service
pkill -f termux-sms-api-server.py
~/bin/start-sms-api.sh
```

## Next Steps

After successful installation:

1. **[Quick Start](quick-start.md)** - Test your installation
2. **[Security Setup](../security/security-setup.md)** - Review security configuration
3. **[User Management](../guides/user-management.md)** - Add team members
4. **[Testing Guide](../guides/testing.md)** - Verify all functionality

## Related Documentation

- [Environment Variables](../reference/environment-variables.md) - All configuration options
- [Deployment Guide](../deployment/deployment-guide.md) - Advanced deployment topics
- [Troubleshooting](../guides/troubleshooting.md) - Common issues