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:

# 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:

# 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
• Termux:API

Configure Termux

Open Termux and run:

# 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:

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

# Should display recent SMS (if any)

Step 4: Clone the Repository

On Ubuntu:

# 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:

cd /mnt/storagessd1tb/campaign_connector

Step 5: Configure Environment

Create your .env file:

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

# Edit configuration
nano .env

Set these required values:

# 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:

python3 src/core/auth.py

Add the generated keys to your .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:

chmod 600 .env

Step 7: Deploy to Android

Test connectivity:

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

Run the deployment script:

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

# 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:

ssh -p 8022 android-dev@YOUR_ANDROID_IP

Set the API key:

# 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):

~/bin/start-all-services.sh

Or start individually:

# 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

# 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

# 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

# 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

# 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

# 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

# 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 - Test your installation
2. Security Setup - Review security configuration
3. User Management - Add team members
4. Testing Guide - Verify all functionality

Related Documentation

• Environment Variables - All configuration options
• Deployment Guide - Advanced deployment topics
• Troubleshooting - Common issues