torrent-gateway/docs/systemd_deployment.md

# Systemd Native Deployment Guide

## Overview

This guide covers deploying Torrent Gateway as native systemd services without Docker, including complete monitoring stack setup.

## Quick Installation

**Complete installation with monitoring:**
```bash
sudo ./scripts/install_native.sh --with-monitoring
```

**Gateway only (no monitoring):**
```bash
sudo ./scripts/install_native.sh
```

## Manual Installation Steps

### 1. Prerequisites

**System Requirements:**
- Ubuntu 20.04+ or Debian 11+
- 4GB+ RAM
- 50GB+ disk space
- Go 1.21+ (installed automatically)

**Install dependencies:**
```bash
sudo apt-get update
sudo apt-get install -y golang-go git sqlite3 redis-server nginx
```

### 2. Build Application

```bash
# Build optimized binary
go build -o bin/gateway \
    -ldflags "-X main.version=$(git describe --tags --always) -X main.buildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ) -s -w" \
    cmd/gateway/main.go

# Verify build
./bin/gateway --version
```

### 3. Install and Configure

**Run systemd setup:**
```bash
sudo ./scripts/setup_systemd.sh
```

This script will:
- Create `torrent-gateway` system user
- Install binary to `/opt/torrent-gateway/`
- Create systemd service file
- Configure nginx reverse proxy
- Setup log rotation
- Configure Redis optimization

### 4. Service Management

**Start services:**
```bash
# Start gateway
sudo systemctl start torrent-gateway
sudo systemctl enable torrent-gateway

# Start dependencies
sudo systemctl start redis-server nginx
sudo systemctl enable redis-server nginx
```

**Check status:**
```bash
# Service status
sudo systemctl status torrent-gateway

# View logs
sudo journalctl -u torrent-gateway -f

# Check all related services
sudo systemctl status torrent-gateway redis-server nginx
```

## Configuration

### Service Configuration

**Systemd service file:** `/etc/systemd/system/torrent-gateway.service`
```ini
[Unit]
Description=Torrent Gateway Server
After=network.target redis.service
Wants=redis.service

[Service]
Type=simple
User=torrent-gateway
Group=torrent-gateway
WorkingDirectory=/opt/torrent-gateway
ExecStart=/opt/torrent-gateway/bin/gateway
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

# Environment variables
Environment=PORT=9876
Environment=DB_PATH=/opt/torrent-gateway/data/metadata.db
Environment=BLOB_DIR=/opt/torrent-gateway/data/blobs
Environment=CHUNK_DIR=/opt/torrent-gateway/data/chunks
Environment=LOG_LEVEL=info

# Security settings
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/torrent-gateway/data
ReadWritePaths=/opt/torrent-gateway/logs

[Install]
WantedBy=multi-user.target
```

### Environment Variables

**Configure in service file or environment:**
```bash
# Core settings
PORT=9876
DB_PATH=/opt/torrent-gateway/data/metadata.db
BLOB_DIR=/opt/torrent-gateway/data/blobs
CHUNK_DIR=/opt/torrent-gateway/data/chunks

# Performance tuning
MAX_UPLOAD_SIZE=1073741824  # 1GB
CHUNK_SIZE=262144           # 256KB
MAX_CONCURRENT_UPLOADS=10

# Security settings
RATE_LIMIT_UPLOAD=10/minute
RATE_LIMIT_DOWNLOAD=100/minute
AUTH_TOKEN_EXPIRY=86400     # 24 hours

# Logging
LOG_LEVEL=info
LOG_FORMAT=json
LOG_FILE=/opt/torrent-gateway/logs/gateway.log
```

### Database Configuration

**SQLite Optimization:**
```bash
# Configure SQLite for production
sqlite3 /opt/torrent-gateway/data/metadata.db << 'EOF'
PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA cache_size = 10000;
PRAGMA temp_store = memory;
PRAGMA mmap_size = 268435456;
EOF
```

## Monitoring Stack Setup

### Native Prometheus Installation

**Install Prometheus:**
```bash
# Download and install
PROMETHEUS_VERSION="2.48.0"
cd /tmp
wget "https://github.com/prometheus/prometheus/releases/download/v${PROMETHEUS_VERSION}/prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz"
tar -xzf prometheus-${PROMETHEUS_VERSION}.linux-amd64.tar.gz

# Install to system
sudo mkdir -p /opt/prometheus
sudo cp prometheus-${PROMETHEUS_VERSION}.linux-amd64/prometheus /opt/prometheus/
sudo cp prometheus-${PROMETHEUS_VERSION}.linux-amd64/promtool /opt/prometheus/
sudo cp -r prometheus-${PROMETHEUS_VERSION}.linux-amd64/console_libraries /opt/prometheus/
sudo cp -r prometheus-${PROMETHEUS_VERSION}.linux-amd64/consoles /opt/prometheus/

# Create prometheus user
sudo useradd --system --shell /bin/false prometheus
sudo mkdir -p /opt/prometheus/data
sudo chown -R prometheus:prometheus /opt/prometheus
```

**Prometheus systemd service:**
```ini
[Unit]
Description=Prometheus
After=network.target

[Service]
Type=simple
User=prometheus
Group=prometheus
ExecStart=/opt/prometheus/prometheus \
    --config.file=/opt/prometheus/prometheus.yml \
    --storage.tsdb.path=/opt/prometheus/data \
    --web.console.templates=/opt/prometheus/consoles \
    --web.console.libraries=/opt/prometheus/console_libraries \
    --web.listen-address=0.0.0.0:9090
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

### Native Grafana Installation

**Install from package:**
```bash
# Add Grafana repository
sudo apt-get install -y software-properties-common
wget -q -O - https://packages.grafana.com/gpg.key | sudo apt-key add -
echo "deb https://packages.grafana.com/oss/deb stable main" | sudo tee /etc/apt/sources.list.d/grafana.list

# Install Grafana
sudo apt-get update
sudo apt-get install -y grafana

# Enable and start
sudo systemctl enable grafana-server
sudo systemctl start grafana-server
```

### Node Exporter for System Metrics

**Install Node Exporter:**
```bash
NODE_EXPORTER_VERSION="1.7.0"
cd /tmp
wget "https://github.com/prometheus/node_exporter/releases/download/v${NODE_EXPORTER_VERSION}/node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz"
tar -xzf node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64.tar.gz

sudo mkdir -p /opt/node_exporter
sudo cp node_exporter-${NODE_EXPORTER_VERSION}.linux-amd64/node_exporter /opt/node_exporter/
sudo chown -R prometheus:prometheus /opt/node_exporter
```

**Node Exporter systemd service:**
```ini
[Unit]
Description=Node Exporter
After=network.target

[Service]
Type=simple
User=prometheus
Group=prometheus
ExecStart=/opt/node_exporter/node_exporter
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

## Performance Optimization

### Systemd Resource Management

**Configure resource limits:**
```bash
# Edit service file
sudo systemctl edit torrent-gateway
```

Add resource limits:
```ini
[Service]
# Memory limits
MemoryMax=2G
MemoryHigh=1.5G

# CPU limits
CPUQuota=200%

# File descriptor limits
LimitNOFILE=65536

# Process limits
LimitNPROC=4096
```

### System Tuning

**Kernel parameters for performance:**
```bash
cat >> /etc/sysctl.conf << 'EOF'
# File system performance
fs.file-max = 65536
vm.dirty_ratio = 10
vm.dirty_background_ratio = 5

# Network performance
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216
EOF

sudo sysctl -p
```

## Backup and Maintenance

### Automated Maintenance

**Cron jobs configured automatically:**
```bash
# Daily backup at 2 AM
0 2 * * * root /opt/torrent-gateway/scripts/backup.sh

# Database maintenance at 3 AM  
0 3 * * * root /opt/torrent-gateway/scripts/migrate.sh

# Health check every 5 minutes
*/5 * * * * root /opt/torrent-gateway/scripts/health_check.sh
```

### Manual Maintenance

**Service restart:**
```bash
sudo systemctl restart torrent-gateway
```

**Database maintenance:**
```bash
sudo /opt/torrent-gateway/scripts/migrate.sh
```

**Log rotation:**
```bash
sudo logrotate /etc/logrotate.d/torrent-gateway
```

## Troubleshooting

### Service Issues

**Check service status:**
```bash
# Detailed status
sudo systemctl status torrent-gateway --no-pager -l

# Recent logs
sudo journalctl -u torrent-gateway --since "10 minutes ago"

# Follow logs in real-time
sudo journalctl -u torrent-gateway -f
```

**Common issues:**
1. **Permission errors:**
   ```bash
   sudo chown -R torrent-gateway:torrent-gateway /opt/torrent-gateway/data/
   ```

2. **Redis connection issues:**
   ```bash
   sudo systemctl status redis-server
   redis-cli ping
   ```

3. **Port conflicts:**
   ```bash
   sudo netstat -tulpn | grep 9876
   ```

### Performance Issues

**Check resource usage:**
```bash
# CPU and memory usage by service
sudo systemd-cgtop

# Detailed resource usage
sudo systemctl show torrent-gateway --property=MemoryCurrent,CPUUsageNSec
```

**Database performance:**
```bash
# Check database locks
sudo lsof /opt/torrent-gateway/data/metadata.db

# Analyze slow queries
sqlite3 /opt/torrent-gateway/data/metadata.db "EXPLAIN QUERY PLAN SELECT * FROM files LIMIT 10;"
```

## Security Hardening

### Service Security

**Systemd security features (already configured):**
- `NoNewPrivileges=true` - Prevents privilege escalation
- `PrivateTmp=true` - Private /tmp directory
- `ProtectSystem=strict` - Read-only file system except specified paths
- `ProtectHome=true` - No access to user home directories

**Additional hardening:**
```bash
# AppArmor profile (optional)
sudo apt-get install apparmor-utils
sudo aa-genprof /opt/torrent-gateway/bin/gateway
```

### File System Security

**Secure installation directory:**
```bash
# Set strict permissions
sudo chmod 750 /opt/torrent-gateway/
sudo chmod 700 /opt/torrent-gateway/data/
sudo chmod 600 /opt/torrent-gateway/configs/*.yml
```

## Migration from Docker

### Migration Process

**Export from Docker deployment:**
```bash
# Create backup from Docker deployment
docker-compose -f docker-compose.prod.yml exec gateway /scripts/backup.sh

# Copy backup out of container
docker cp container_name:/app/backups/gateway_backup_*.tar.gz ./
```

**Import to systemd deployment:**
```bash
# Install systemd version
sudo ./scripts/install_native.sh

# Restore data
sudo ./scripts/restore.sh <backup_timestamp>

# Verify migration
sudo ./scripts/health_check.sh
```

## Advantages of Native Deployment

**Performance Benefits:**
- Direct hardware access
- No container overhead
- Optimized system resource usage
- Better integration with system tools

**Operational Benefits:**
- Standard systemd service management
- Native log integration with journald
- Direct file system access
- Easier debugging and troubleshooting

**Security Benefits:**
- Reduced attack surface
- Native systemd security features
- Direct integration with system security tools
- Simplified security auditing