admin
498e1ab6ca
- Refactored the dashboard html into seperate pages and all the necessary components - Added login and secured api routes / debugged getting system working on a tailnet. - added some functionality to the debugging and health endpoints - added in a new phone contact import and debugged.
288 lines
6.5 KiB
Markdown
288 lines
6.5 KiB
Markdown
# 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)
|