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)
- HTTPS/SSL configuration (via Let's Encrypt)
- JWT-based authentication
- Nginx reverse proxy configuration
- Systemd service for process management
- Firewall configuration
- Automated backups
- Security headers

## 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
   - Configure Nginx
   - Get SSL certificate
   - Setup systemd service
   - Configure firewall
   - Setup automated backups

4. Follow prompts to:
   - Enter your domain name
   - Enter your email (for SSL)
   - Configure your .env file with secrets

## Manual Setup

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

## Free Domain Options

### Option 1: DuckDNS (Recommended)
- Visit https://www.duckdns.org
- Sign in and create a subdomain (e.g., `myfaction.duckdns.org`)
- Note your token for DNS updates
- Free HTTPS support with Let's Encrypt

### Option 2: FreeDNS
- Visit https://freedns.afraid.org
- Create free subdomain
- Choose from many domain options

### Option 3: No-IP
- Visit https://www.noip.com
- Free tier includes dynamic DNS

## 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
```
https://yourdomain.com
```

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

## Configuration

### Option 1: Web Interface (Recommended)
1. Visit `https://yourdomain.com/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

## Security Checklist

Before going live, verify:

- [ ] Strong AUTH_PASSWORD generated and set
- [ ] Strong JWT_SECRET generated and set
- [ ] HTTPS/SSL certificate installed
- [ ] Firewall configured (only ports 22, 80, 443)
- [ ] Port 8000 blocked from external access
- [ ] .env file has permissions 600
- [ ] data/ directory has permissions 700
- [ ] Automatic SSL renewal working
- [ ] Backups configured (2 AM daily)
- [ ] Logs accessible and monitoring setup

## 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 SSL Certificate
```bash
# Auto-renewal is configured by certbot
# Test renewal:
sudo certbot renew --dry-run
```

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

### 502 Bad Gateway
```bash
# Check if app is running
sudo systemctl status faction-war

# Check if listening on port 8000
sudo netstat -tlnp | grep 8000
```

### SSL Certificate Issues
```bash
# Renew manually
sudo certbot renew

# Check certificate status
sudo certbot certificates
```

## 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
sudo tail -f /var/log/nginx/faction-war-error.log

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

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

# Renew SSL
sudo certbot renew
```

## Monitoring

Monitor these logs regularly:
- Application: `sudo journalctl -u faction-war -f`
- Nginx Access: `/var/log/nginx/faction-war-access.log`
- Nginx Errors: `/var/log/nginx/faction-war-error.log`
- System: `sudo tail -f /var/log/syslog`

## Production Best Practices

1. **Use strong passwords** - Generate with OpenSSL
2. **Keep dependencies updated** - Regular `pip install --upgrade`
3. **Monitor logs** - Check for errors and suspicious activity
4. **Backup regularly** - Automated daily backups configured
5. **Use HTTPS only** - HTTP auto-redirects to HTTPS
6. **Restrict firewall** - Only necessary ports open
7. **Update system** - Regular `apt update && apt upgrade`
8. **Test backups** - Periodically restore from backup to verify

## 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!