# Environment Variables Reference

Configuration guide for `.env` file settings.

## Required Variables

### Android Device Configuration

```env
# 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

```env
# 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

```env
# 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

```env
# 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**:
```bash
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

```env
# 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)

```env
# 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

```env
# 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

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

```env
# 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`:
```bash
# Restart Docker to reload environment
docker compose down
docker compose up -d
```

### Missing Variables

```bash
# 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

```bash
# 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](../setup/quick-start.md)
- [Security Setup](../security/security-setup.md)
- [Deployment Guide](../deployment/deployment-guide.md)