campaign_connector/docs/reference/environment-variables.md

Environment Variables Reference

Configuration guide for .env file settings.

Required Variables

Android Device Configuration

# Your Android device's IP address
# Use Tailscale IP for best reliability
PHONE_IP=100.107.173.66

# ADB wireless debugging port (optional, only for ADB fallback)
ADB_PORT=5555

# Termux API server port
TERMUX_API_PORT=5001

PHONE_IP: IP address of your Android device

• Recommended: Use Tailscale IP (e.g., 100.x.x.x)
• Alternative: Local network IP (e.g., 192.168.x.x)
• Find with: tailscale ip -4 on Android

ADB_PORT: Port for ADB wireless debugging

• Default: 5555
• Only needed if using ADB fallback
• Can be omitted if using Termux API only

TERMUX_API_PORT: Port where Termux API server runs

• Default: 5001
• Must match port in Android Termux server

Flask Application

# Application environment
FLASK_ENV=production

# Secret key for session encryption
SECRET_KEY=your-very-secret-random-string-here

# Delay between SMS messages (seconds)
DEFAULT_DELAY_SECONDS=3

FLASK_ENV: Application environment mode

• Values: production, development
• Production: Disables debug mode, optimizes performance
• Development: Enables debug mode, detailed errors

SECRET_KEY: Encryption key for sessions

• Generate with: python3 -c "import secrets; print(secrets.token_hex(32))"
• Must be random and secret
• Change this from default!

DEFAULT_DELAY_SECONDS: Delay between sending SMS

• Default: 3 seconds
• Prevents carrier rate limiting
• Lower = faster (but may trigger spam detection)
• Higher = slower (but more reliable)

SMS Retry Configuration

# Maximum retry attempts for failed SMS
SMS_MAX_RETRIES=3

# Initial retry delay (exponential backoff)
SMS_RETRY_BASE_DELAY=2

# Maximum retry delay
SMS_MAX_RETRY_DELAY=8

SMS_MAX_RETRIES: Number of retry attempts

• Default: 3
• How many times to retry failed messages
• Set to 0 to disable retries

SMS_RETRY_BASE_DELAY: Base delay for exponential backoff

• Default: 2 seconds
• First retry after 2s, second after 4s, third after 8s

SMS_MAX_RETRY_DELAY: Maximum delay cap

• Default: 8 seconds
• Prevents delays from growing too long

Security Variables

API Keys

# Admin API key (full access)
ADMIN_API_KEY=your-admin-api-key-here

# User API key (regular access)
USER_API_KEY=your-user-api-key-here

# Termux API key (Android communication)
TERMUX_API_KEY=your-termux-api-key-here

# Termux API secret (same as TERMUX_API_KEY)
TERMUX_API_SECRET=same-as-termux-api-key

Generate all keys with:

python3 src/core/auth.py

ADMIN_API_KEY: Full system access

• Use for: Admin operations, database resets
• Keep this secret and secure

USER_API_KEY: Regular operations

• Use for: Campaigns, SMS sending, analytics
• Share with trusted team members only

TERMUX_API_KEY: Android device communication

• Use for: Internal communication with Termux server
• Used automatically by connection manager

TERMUX_API_SECRET: Android server authentication

• Must match TERMUX_API_KEY
• Set on both Ubuntu server and Android device

User Management

# Default admin user (created on first startup)
ADMIN_USERNAME=admin
ADMIN_PASSWORD=ChangeThisPassword123!

ADMIN_USERNAME: Initial admin username

• Created automatically on first run
• Can be changed via user management

ADMIN_PASSWORD: Initial admin password

• Used to create first admin account
• Should be strong and unique
• Can be removed from .env after admin is created

Optional Variables

SMS Automation (ADB Fallback Only)

# Screen coordinates for send button (device-specific)
SEND_BUTTON_X=1300
SEND_BUTTON_Y=2900

SEND_BUTTON_X/Y: Touch coordinates for SMS send button

• Only needed if using ADB fallback
• Device and screen resolution specific
• Find with: adb shell getevent while tapping

Database Configuration

# Database file path (relative to project root)
DATABASE_PATH=data/campaign.db

DATABASE_PATH: Location of SQLite database

• Default: data/campaign.db
• Automatically created if doesn't exist
• Backed up by Docker volume

Upload Configuration

# Maximum CSV file size (bytes)
MAX_UPLOAD_SIZE=5242880  # 5MB

# Upload folder path
UPLOAD_FOLDER=uploads

MAX_UPLOAD_SIZE: Maximum CSV upload size

• Default: 5MB (5242880 bytes)
• Increase for larger contact lists

UPLOAD_FOLDER: CSV storage directory

• Default: uploads/
• Mounted as Docker volume

Example .env File

Complete example configuration:

# Android Device (Tailscale)
PHONE_IP=100.107.173.66
ADB_PORT=5555
TERMUX_API_PORT=5001

# Flask Application
FLASK_ENV=production
SECRET_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
DEFAULT_DELAY_SECONDS=3

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

# API Keys (generate with: python3 src/core/auth.py)
ADMIN_API_KEY=your-generated-admin-key-here
USER_API_KEY=your-generated-user-key-here
TERMUX_API_KEY=your-generated-termux-key-here
TERMUX_API_SECRET=your-generated-termux-key-here

# User Management
ADMIN_USERNAME=admin
ADMIN_PASSWORD=YourSecurePassword123!

# ADB Fallback (optional)
SEND_BUTTON_X=1300
SEND_BUTTON_Y=2900

Security Best Practices

DO:

• Generate strong, random API keys
• Use Tailscale IP for PHONE_IP
• Keep .env file secret
• Set restrictive file permissions: chmod 600 .env
• Back up .env securely (encrypted)
• Rotate API keys every 90 days

DON'T:

• Commit .env to version control (use .env.example)
• Share .env file in plain text
• Use default or weak SECRET_KEY
• Hardcode values in application code
• Log environment variables

Troubleshooting

Changes Not Applied

After modifying .env:

# Restart Docker to reload environment
docker compose down
docker compose up -d

Missing Variables

# Check which variables are loaded
docker compose exec sms-campaign env | grep -E "(API_KEY|PHONE_IP|SECRET_KEY)"

# Verify .env file format (no spaces around =)
cat .env

Permission Denied

# Fix file permissions
chmod 600 .env

# Verify ownership
ls -l .env

Environment Variable Loading

Variables are loaded in this order:

1. .env file in project root
2. Docker Compose environment section
3. System environment variables (highest priority)

Docker Compose automatically loads .env file if present.

Related Documentation

• Quick Start Guide
• Security Setup
• Deployment Guide