campaign_connector/docs/setup/quick-start.md

Quick Start Guide

This guide covers rapid deployment and testing after you've completed the Installation Guide.

Prerequisites

Before starting, ensure you have:

• .env file configured with API keys and admin credentials
• Docker installed on Ubuntu server
• Android device accessible via SSH
• Termux API server deployed

If not, complete the Installation Guide first.

Deploy in 3 Steps

Step 1: Deploy to Android

cd /mnt/storagessd1tb/campaign_connector
./scripts/deploy-android.sh

Wait for: Deployment Complete!

Step 2: Start Docker

docker compose down && docker compose build && docker compose up -d

Wait for container to be healthy:

docker compose ps
# STATUS should show "healthy"

Step 3: Verify Services

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

# Test Android server (replace with your IP)
curl http://YOUR_ANDROID_IP:5001/health

Both should return healthy status.

Quick Tests

Web Dashboard Login

1. Open browser: http://localhost:5000/
2. Should redirect to login page
3. Log in with your admin credentials (from .env)
4. Dashboard should load without errors

API Authentication

# Should FAIL (no API key)
curl http://localhost:5000/api/campaign/list
# Expected: 401 Unauthorized

# Should SUCCEED (with API key from .env)
curl -H "X-API-Key: YOUR_USER_API_KEY" http://localhost:5000/api/campaign/list
# Expected: JSON response with campaigns

Send Test SMS

curl -X POST http://localhost:5000/api/sms/test/real \
  -H "X-API-Key: YOUR_USER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"YOUR_PHONE_NUMBER","message":"Test from SMS Campaign Manager"}'

Common Commands

Service Management

# Start services
docker compose up -d

# Stop services
docker compose down

# View logs
docker compose logs -f sms-campaign

# Restart container
docker compose restart

Android Services

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

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

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

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

User Management

# Create new user
python3 manage_users.py
# Select option 1, follow prompts

# List users
python3 manage_users.py
# Select option 2

Credentials Reference

After setup, your credentials are stored in .env:

Credential	Variable	Purpose
Admin username	ADMIN_USERNAME	Web dashboard login
Admin password	ADMIN_PASSWORD	Web dashboard login
User API key	USER_API_KEY	API access for scripts
Admin API key	ADMIN_API_KEY	Admin operations
Termux API key	TERMUX_API_KEY	Android communication

API Key Usage

# Header method
curl -H "X-API-Key: YOUR_KEY" http://localhost:5000/api/endpoint

# Bearer token method
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:5000/api/endpoint

Service URLs

Service	URL
Web Dashboard	http://localhost:5000
Login Page	http://localhost:5000/login
Health Check	http://localhost:5000/health
Android API	http://YOUR_ANDROID_IP:5001/health

Troubleshooting

Can't Login

# Check if admin was created
docker compose logs | grep "Created admin"

# Create user manually
python3 manage_users.py

API Key Not Working

# Verify keys are loaded
docker compose exec sms-campaign env | grep API_KEY

# Restart to reload
docker compose restart

Android Not Responding

# Check connectivity
ping YOUR_ANDROID_IP

# View Android logs
ssh -p 8022 android-dev@YOUR_ANDROID_IP "tail -20 ~/logs/sms-api.log"

# Redeploy
./scripts/deploy-android.sh

Success Checklist

After deployment, verify:

• Docker container running and healthy
• Can access login page at /login
• Can log in as admin
• Dashboard loads without errors
• API calls require authentication
• Android health check passes
• Test SMS sends successfully

Next Steps

1. Create team users: Use manage_users.py
2. Import contacts: Upload CSV via web dashboard
3. Create campaign: Set up your first SMS campaign
4. Review security: See Security Setup

Related Documentation

• Installation Guide - Complete setup instructions
• Authentication Setup - User login details
• User Management - Managing users
• Testing Guide - Comprehensive testing
• Troubleshooting - Common issues