faction_war_dispatch_bot/PRODUCTION_README.md

# Faction War Dispatch Bot - Production Deployment

## Quick Summary

This application is ready for production deployment with proper security measures. Follow the steps below to deploy to your Linux server.

## Security Features Implemented

- Environment variable support (.env files)
- Secrets excluded from git (.gitignore)
- JWT-based authentication
- Systemd service for process management
- Firewall configuration
- Automated backups
- Ready for reverse proxy integration (nginx, caddy, traefik, etc.)

## Prerequisites

- **Server**: Linux VM (Ubuntu 20.04+ or Debian 11+)
- **RAM**: 512MB minimum, 1GB recommended
- **Domain**: Free domain from DuckDNS, FreeDNS, or No-IP
- **Port Access**: Ports 80 and 443 open to the internet

## Automated Setup (Recommended)

1. Upload files to your server:
   ```bash
   scp -r * user@your-server:/opt/faction-war/app/
   ```

2. Run the setup script:
   ```bash
   ssh user@your-server
   cd /opt/faction-war/app
   sudo bash setup_production.sh
   ```

3. The script will:
   - Install all dependencies
   - Setup systemd service
   - Configure firewall
   - Setup automated backups
   - Start the application on HTTP

4. Follow prompts to:
   - Choose application port (default: 8000)
   - Configure your .env file with secrets

5. Configure your reverse proxy separately for HTTPS

## Manual Setup

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed step-by-step instructions.

## Reverse Proxy Options (for HTTPS)

The application runs on HTTP. You'll need to configure a reverse proxy for HTTPS:

### Option 1: Nginx
- Simple configuration
- Widely used and documented
- Free SSL with Let's Encrypt/Certbot

### Option 2: Caddy
- Automatic HTTPS with built-in Let's Encrypt
- Simple configuration file
- Recommended for ease of use

### Option 3: Traefik
- Great for containerized deployments
- Automatic SSL certificate management
- Dynamic configuration

### Free Domain Options:
- **DuckDNS** (https://www.duckdns.org) - Free subdomain
- **FreeDNS** (https://freedns.afraid.org) - Multiple domain options
- **No-IP** (https://www.noip.com) - Dynamic DNS support

## Critical Security Steps

### Before Deployment:

1. **Generate Strong Secrets**:
   ```bash
   # Generate AUTH_PASSWORD
   openssl rand -base64 32

   # Generate JWT_SECRET
   openssl rand -hex 64
   ```

2. **Configure .env File**:
   ```bash
   cp .env.example .env
   nano .env
   ```

   Update these values:
   ```env
   AUTH_PASSWORD=<generated-password>
   JWT_SECRET=<generated-secret>
   TORN_API_KEY=<your-api-key>
   DISCORD_TOKEN=<your-bot-token>
   ```

3. **Secure .env File**:
   ```bash
   chmod 600 .env
   ```

4. **Never Commit Secrets**:
   - `.env` is in `.gitignore`
   - `data/config.json` is in `.gitignore`
   - Never commit API keys or passwords

## Post-Deployment

### Access Your Application
```
Local: http://localhost:8000 (or your configured port)
Remote: http://YOUR_SERVER_IP:8000
```

### Check Service Status
```bash
sudo systemctl status faction-war
```

### View Logs
```bash
sudo journalctl -u faction-war -f
```

### Restart Service
```bash
sudo systemctl restart faction-war
```

### Configure Reverse Proxy
Set up your reverse proxy (nginx, caddy, etc.) to:
- Listen on ports 80/443
- Forward requests to `http://127.0.0.1:8000` (or your configured port)
- Handle SSL/TLS termination
- Add security headers

## Configuration

### Option 1: Web Interface (Recommended)
1. Visit your application URL (e.g., `http://yourserver:8000/config`)
2. Configure all settings through the UI
3. Settings are saved to `data/config.json`

### Option 2: Environment Variables
1. Edit `/opt/faction-war/app/.env`
2. Restart service: `sudo systemctl restart faction-war`

### Option 3: JSON File
1. Edit `data/config.json` directly
2. Restart service to apply changes

**Priority**: Environment variables > config.json > defaults

**Note**: Once you configure your reverse proxy with HTTPS, access via secure URL

## Security Checklist

Before going live, verify:

- [ ] Strong AUTH_PASSWORD generated and set
- [ ] Strong JWT_SECRET generated and set
- [ ] Reverse proxy configured with HTTPS/SSL
- [ ] Firewall configured (SSH + application port only)
- [ ] Application port accessible only via reverse proxy (if using one)
- [ ] .env file has permissions 600
- [ ] data/ directory has permissions 700
- [ ] Backups configured (2 AM daily)
- [ ] Logs accessible and monitoring setup
- [ ] Security headers configured on reverse proxy

## File Structure

```
/opt/faction-war/app/
├── main.py                 # Application entry point
├── config.py               # Configuration loader
├── .env                    # Environment variables (NEVER COMMIT)
├── .env.example            # Example environment file
├── requirements.txt        # Python dependencies
├── faction-war.service     # Systemd service template
├── nginx.conf.example      # Nginx configuration template
├── setup_production.sh     # Automated setup script
├── DEPLOYMENT.md           # Detailed deployment guide
├── data/                   # Persistent data (NEVER COMMIT)
│   ├── config.json        # Web UI configuration
│   ├── discord_mapping.json
│   └── ...
├── routers/               # API routes
├── services/              # Business logic
├── static/                # Frontend assets
└── templates/             # HTML templates
```

## Updates

### Update Application
```bash
cd /opt/faction-war/app
git pull
sudo -u factionwar venv/bin/pip install --upgrade -r requirements.txt
sudo systemctl restart faction-war
```

### Update Reverse Proxy Configuration
Configure SSL certificate renewal in your reverse proxy (nginx, caddy, etc.)

## Backups

Automated daily backups run at 2 AM:
- Location: `/opt/faction-war/backups/`
- Retention: 7 days
- Manual backup:
  ```bash
  /opt/faction-war/backup.sh
  ```

## Troubleshooting

### Application Won't Start
```bash
# Check logs
sudo journalctl -u faction-war -n 50

# Test manually
sudo -u factionwar /opt/faction-war/app/venv/bin/python /opt/faction-war/app/main.py
```

### Cannot Connect to Application
```bash
# Check if app is running
sudo systemctl status faction-war

# Check if listening on configured port
sudo netstat -tlnp | grep 8000  # or your configured port

# Check firewall rules
sudo ufw status

# Test direct connection
curl http://localhost:8000
```

### Reverse Proxy Issues
Refer to your reverse proxy documentation (nginx, caddy, etc.) for SSL/HTTPS troubleshooting

## Support

For detailed deployment instructions, see [DEPLOYMENT.md](DEPLOYMENT.md)

## Quick Commands Reference

```bash
# Service management
sudo systemctl start faction-war
sudo systemctl stop faction-war
sudo systemctl restart faction-war
sudo systemctl status faction-war

# View logs
sudo journalctl -u faction-war -f

# Update application
cd /opt/faction-war/app && git pull && sudo systemctl restart faction-war

# Manual backup
/opt/faction-war/backup.sh

# Check if application is listening
sudo netstat -tlnp | grep 8000  # or your port

# Test application directly
curl http://localhost:8000
```

## Monitoring

Monitor these logs regularly:
- Application: `sudo journalctl -u faction-war -f`
- Reverse Proxy: Check your proxy logs (nginx, caddy, etc.)
- System: `sudo tail -f /var/log/syslog`

## Production Best Practices

1. **Use strong passwords** - Generate with OpenSSL
2. **Configure HTTPS** - Use a reverse proxy with SSL/TLS
3. **Keep dependencies updated** - Regular `pip install --upgrade`
4. **Monitor logs** - Check for errors and suspicious activity
5. **Backup regularly** - Automated daily backups configured
6. **Restrict firewall** - Only necessary ports open
7. **Update system** - Regular `apt update && apt upgrade`
8. **Test backups** - Periodically restore from backup to verify
9. **Secure headers** - Configure security headers on your reverse proxy

## Features

- Secure authentication (JWT + password)
- Web-based configuration
- Real-time activity logging
- Active user tracking
- Automated hit assignment
- Chain timer monitoring
- Server-side state persistence
- Multi-device support

---

**Ready to deploy?** Run `setup_production.sh` on your server to get started!