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:

sudo ./scripts/install_native.sh --with-monitoring

Gateway only (no monitoring):

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:

sudo apt-get update
sudo apt-get install -y golang-go git sqlite3 redis-server nginx

2. Build Application

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

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:

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

# 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

[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:

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

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

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

[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:

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

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:

[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:

# Edit service file
sudo systemctl edit torrent-gateway

Add resource limits:

[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:

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:

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

sudo systemctl restart torrent-gateway

Database maintenance:

sudo /opt/torrent-gateway/scripts/migrate.sh

Log rotation:

sudo logrotate /etc/logrotate.d/torrent-gateway

Troubleshooting

Service Issues

Check service status:

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

   sudo chown -R torrent-gateway:torrent-gateway /opt/torrent-gateway/data/
   

2. Redis connection issues:

   sudo systemctl status redis-server
   redis-cli ping
   

3. Port conflicts:

   sudo netstat -tulpn | grep 9876
   

Performance Issues

Check resource usage:

# CPU and memory usage by service
sudo systemd-cgtop

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

Database performance:

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

# AppArmor profile (optional)
sudo apt-get install apparmor-utils
sudo aa-genprof /opt/torrent-gateway/bin/gateway

File System Security

Secure installation directory:

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

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

# 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