v0.3.0 - Complete deployment documentation and examples - Added comprehensive deployment guide, automated deployment scripts, nginx SSL proxy setup, backup automation, and monitoring tools. Includes VPS deployment, cloud platform guides, and practical examples for production deployment of event-based configuration system.
This commit is contained in:
Your Name
600
docs/deployment_guide.md
Normal file
600
docs/deployment_guide.md
Normal file
@@ -0,0 +1,600 @@
|
||||
# Deployment Guide - C Nostr Relay
|
||||
|
||||
Complete deployment guide for the C Nostr Relay with event-based configuration system across different environments and platforms.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Deployment Overview](#deployment-overview)
|
||||
- [Production Deployment](#production-deployment)
|
||||
- [Cloud Deployments](#cloud-deployments)
|
||||
- [Container Deployment](#container-deployment)
|
||||
- [Reverse Proxy Setup](#reverse-proxy-setup)
|
||||
- [Monitoring Setup](#monitoring-setup)
|
||||
- [Security Hardening](#security-hardening)
|
||||
- [Backup and Recovery](#backup-and-recovery)
|
||||
|
||||
## Deployment Overview
|
||||
|
||||
The C Nostr Relay's event-based configuration system simplifies deployment:
|
||||
|
||||
### Key Deployment Benefits
|
||||
- **Zero Configuration**: No config files to manage or transfer
|
||||
- **Self-Contained**: Single binary + auto-generated database
|
||||
- **Portable**: Database contains all relay state and configuration
|
||||
- **Secure**: Admin keys generated locally, never transmitted
|
||||
- **Scalable**: Efficient SQLite backend with WAL mode
|
||||
|
||||
### Deployment Requirements
|
||||
- **CPU**: 1 vCPU minimum, 2+ recommended
|
||||
- **RAM**: 512MB minimum, 2GB+ recommended
|
||||
- **Storage**: 100MB for binary + database growth (varies by usage)
|
||||
- **Network**: Port 8888 (configurable via events)
|
||||
- **OS**: Linux (recommended), macOS, Windows (WSL)
|
||||
|
||||
## Production Deployment
|
||||
|
||||
### Server Preparation
|
||||
|
||||
#### System Updates
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum update -y
|
||||
|
||||
# Install required packages
|
||||
sudo apt install -y build-essential git sqlite3 libsqlite3-dev \
|
||||
libwebsockets-dev libssl-dev libsecp256k1-dev libcurl4-openssl-dev \
|
||||
zlib1g-dev systemd
|
||||
```
|
||||
|
||||
#### User and Directory Setup
|
||||
```bash
|
||||
# Create dedicated system user
|
||||
sudo useradd --system --home-dir /opt/c-relay --shell /bin/false c-relay
|
||||
|
||||
# Create application directory
|
||||
sudo mkdir -p /opt/c-relay
|
||||
sudo chown c-relay:c-relay /opt/c-relay
|
||||
```
|
||||
|
||||
### Build and Installation
|
||||
|
||||
#### Automated Installation (Recommended)
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/your-org/c-relay.git
|
||||
cd c-relay
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Build
|
||||
make clean && make
|
||||
|
||||
# Install as systemd service
|
||||
sudo systemd/install-service.sh
|
||||
```
|
||||
|
||||
#### Manual Installation
|
||||
```bash
|
||||
# Build relay
|
||||
make clean && make
|
||||
|
||||
# Install binary
|
||||
sudo cp build/c_relay_x86 /opt/c-relay/
|
||||
sudo chown c-relay:c-relay /opt/c-relay/c_relay_x86
|
||||
sudo chmod +x /opt/c-relay/c_relay_x86
|
||||
|
||||
# Install systemd service
|
||||
sudo cp systemd/c-relay.service /etc/systemd/system/
|
||||
sudo systemctl daemon-reload
|
||||
```
|
||||
|
||||
### Service Management
|
||||
|
||||
#### Start and Enable Service
|
||||
```bash
|
||||
# Start the service
|
||||
sudo systemctl start c-relay
|
||||
|
||||
# Enable auto-start on boot
|
||||
sudo systemctl enable c-relay
|
||||
|
||||
# Check status
|
||||
sudo systemctl status c-relay
|
||||
```
|
||||
|
||||
#### Capture Admin Keys (CRITICAL)
|
||||
```bash
|
||||
# View startup logs to get admin keys
|
||||
sudo journalctl -u c-relay --since "5 minutes ago" | grep -A 10 "IMPORTANT: SAVE THIS ADMIN PRIVATE KEY"
|
||||
|
||||
# Or check the full log
|
||||
sudo journalctl -u c-relay --no-pager | grep "Admin Private Key"
|
||||
```
|
||||
|
||||
⚠️ **CRITICAL**: Save the admin private key immediately - it's only shown once and is needed for all configuration updates!
|
||||
|
||||
### Firewall Configuration
|
||||
|
||||
#### UFW (Ubuntu)
|
||||
```bash
|
||||
# Allow relay port
|
||||
sudo ufw allow 8888/tcp
|
||||
|
||||
# Allow SSH (ensure you don't lock yourself out)
|
||||
sudo ufw allow 22/tcp
|
||||
|
||||
# Enable firewall
|
||||
sudo ufw enable
|
||||
```
|
||||
|
||||
#### iptables
|
||||
```bash
|
||||
# Allow relay port
|
||||
sudo iptables -A INPUT -p tcp --dport 8888 -j ACCEPT
|
||||
|
||||
# Save rules (Ubuntu/Debian)
|
||||
sudo iptables-save > /etc/iptables/rules.v4
|
||||
```
|
||||
|
||||
## Cloud Deployments
|
||||
|
||||
### AWS EC2
|
||||
|
||||
#### Instance Setup
|
||||
```bash
|
||||
# Launch Ubuntu 22.04 LTS instance (t3.micro or larger)
|
||||
# Security Group: Allow port 8888 from 0.0.0.0/0 (or restricted IPs)
|
||||
|
||||
# Connect via SSH
|
||||
ssh -i your-key.pem ubuntu@your-instance-ip
|
||||
|
||||
# Use the simple deployment script
|
||||
git clone https://github.com/your-org/c-relay.git
|
||||
cd c-relay
|
||||
sudo examples/deployment/simple-vps/deploy.sh
|
||||
```
|
||||
|
||||
#### Elastic IP (Recommended)
|
||||
```bash
|
||||
# Associate Elastic IP to ensure consistent public IP
|
||||
# Configure DNS A record to point to Elastic IP
|
||||
```
|
||||
|
||||
#### EBS Volume for Data
|
||||
```bash
|
||||
# Attach EBS volume for persistent storage
|
||||
sudo mkfs.ext4 /dev/xvdf
|
||||
sudo mkdir /data
|
||||
sudo mount /dev/xvdf /data
|
||||
sudo chown c-relay:c-relay /data
|
||||
|
||||
# Update systemd service to use /data
|
||||
sudo sed -i 's/WorkingDirectory=\/opt\/c-relay/WorkingDirectory=\/data/' /etc/systemd/system/c-relay.service
|
||||
sudo systemctl daemon-reload
|
||||
```
|
||||
|
||||
### Google Cloud Platform
|
||||
|
||||
#### Compute Engine Setup
|
||||
```bash
|
||||
# Create VM instance (e2-micro or larger)
|
||||
gcloud compute instances create c-relay-instance \
|
||||
--image-family=ubuntu-2204-lts \
|
||||
--image-project=ubuntu-os-cloud \
|
||||
--machine-type=e2-micro \
|
||||
--tags=nostr-relay
|
||||
|
||||
# Configure firewall
|
||||
gcloud compute firewall-rules create allow-nostr-relay \
|
||||
--allow tcp:8888 \
|
||||
--source-ranges 0.0.0.0/0 \
|
||||
--target-tags nostr-relay
|
||||
|
||||
# SSH and deploy
|
||||
gcloud compute ssh c-relay-instance
|
||||
git clone https://github.com/your-org/c-relay.git
|
||||
cd c-relay
|
||||
sudo examples/deployment/simple-vps/deploy.sh
|
||||
```
|
||||
|
||||
#### Persistent Disk
|
||||
```bash
|
||||
# Create and attach persistent disk
|
||||
gcloud compute disks create relay-data --size=50GB
|
||||
gcloud compute instances attach-disk c-relay-instance --disk=relay-data
|
||||
|
||||
# Format and mount
|
||||
sudo mkfs.ext4 /dev/sdb
|
||||
sudo mkdir /data
|
||||
sudo mount /dev/sdb /data
|
||||
sudo chown c-relay:c-relay /data
|
||||
```
|
||||
|
||||
### DigitalOcean
|
||||
|
||||
#### Droplet Creation
|
||||
```bash
|
||||
# Create Ubuntu 22.04 droplet (Basic plan, $6/month minimum)
|
||||
# Enable monitoring and backups
|
||||
|
||||
# SSH into droplet
|
||||
ssh root@your-droplet-ip
|
||||
|
||||
# Deploy relay
|
||||
git clone https://github.com/your-org/c-relay.git
|
||||
cd c-relay
|
||||
examples/deployment/simple-vps/deploy.sh
|
||||
```
|
||||
|
||||
#### Block Storage
|
||||
```bash
|
||||
# Attach block storage volume
|
||||
# Format and mount as /data
|
||||
sudo mkfs.ext4 /dev/sda
|
||||
sudo mkdir /data
|
||||
sudo mount /dev/sda /data
|
||||
echo '/dev/sda /data ext4 defaults,nofail,discard 0 2' >> /etc/fstab
|
||||
```
|
||||
|
||||
## Automated Deployment Examples
|
||||
|
||||
The `examples/deployment/` directory contains ready-to-use scripts:
|
||||
|
||||
### Simple VPS Deployment
|
||||
```bash
|
||||
# Clone repository and run automated deployment
|
||||
git clone https://github.com/your-org/c-relay.git
|
||||
cd c-relay
|
||||
sudo examples/deployment/simple-vps/deploy.sh
|
||||
```
|
||||
|
||||
### SSL Proxy Setup
|
||||
```bash
|
||||
# Set up nginx reverse proxy with SSL
|
||||
sudo examples/deployment/nginx-proxy/setup-ssl-proxy.sh \
|
||||
-d relay.example.com -e admin@example.com
|
||||
```
|
||||
|
||||
### Monitoring Setup
|
||||
```bash
|
||||
# Set up continuous monitoring
|
||||
sudo examples/deployment/monitoring/monitor-relay.sh \
|
||||
-c -i 60 -e admin@example.com
|
||||
```
|
||||
|
||||
### Backup Setup
|
||||
```bash
|
||||
# Set up automated backups
|
||||
sudo examples/deployment/backup/backup-relay.sh \
|
||||
-s my-backup-bucket -e admin@example.com
|
||||
```
|
||||
|
||||
## Reverse Proxy Setup
|
||||
|
||||
### Nginx Configuration
|
||||
|
||||
#### Basic WebSocket Proxy
|
||||
```nginx
|
||||
# /etc/nginx/sites-available/nostr-relay
|
||||
server {
|
||||
listen 80;
|
||||
server_name relay.yourdomain.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8888;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# WebSocket timeouts
|
||||
proxy_read_timeout 86400s;
|
||||
proxy_send_timeout 86400s;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### HTTPS with Let's Encrypt
|
||||
```bash
|
||||
# Install certbot
|
||||
sudo apt install -y certbot python3-certbot-nginx
|
||||
|
||||
# Obtain certificate
|
||||
sudo certbot --nginx -d relay.yourdomain.com
|
||||
|
||||
# Auto-renewal (crontab)
|
||||
echo "0 12 * * * /usr/bin/certbot renew --quiet" | sudo crontab -
|
||||
```
|
||||
|
||||
#### Enhanced HTTPS Configuration
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name relay.yourdomain.com;
|
||||
|
||||
# SSL configuration
|
||||
ssl_certificate /etc/letsencrypt/live/relay.yourdomain.com/fullchain.pem;
|
||||
ssl_certificate_key /etc/letsencrypt/live/relay.yourdomain.com/privkey.pem;
|
||||
ssl_protocols TLSv1.2 TLSv1.3;
|
||||
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES256-GCM-SHA384;
|
||||
ssl_prefer_server_ciphers off;
|
||||
|
||||
# Security headers
|
||||
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";
|
||||
add_header X-Content-Type-Options nosniff;
|
||||
add_header X-Frame-Options DENY;
|
||||
add_header X-XSS-Protection "1; mode=block";
|
||||
|
||||
# Rate limiting (optional)
|
||||
limit_req_zone $remote_addr zone=relay:10m rate=10r/s;
|
||||
limit_req zone=relay burst=20 nodelay;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:8888;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
|
||||
# WebSocket timeouts
|
||||
proxy_read_timeout 86400s;
|
||||
proxy_send_timeout 86400s;
|
||||
|
||||
# Buffer settings
|
||||
proxy_buffering off;
|
||||
}
|
||||
}
|
||||
|
||||
# Redirect HTTP to HTTPS
|
||||
server {
|
||||
listen 80;
|
||||
server_name relay.yourdomain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
```
|
||||
|
||||
### Apache Configuration
|
||||
|
||||
#### WebSocket Proxy with mod_proxy_wstunnel
|
||||
```apache
|
||||
# Enable required modules
|
||||
sudo a2enmod proxy
|
||||
sudo a2enmod proxy_http
|
||||
sudo a2enmod proxy_wstunnel
|
||||
sudo a2enmod ssl
|
||||
|
||||
# /etc/apache2/sites-available/nostr-relay.conf
|
||||
<VirtualHost *:443>
|
||||
ServerName relay.yourdomain.com
|
||||
|
||||
# SSL configuration
|
||||
SSLEngine on
|
||||
SSLCertificateFile /etc/letsencrypt/live/relay.yourdomain.com/fullchain.pem
|
||||
SSLCertificateKeyFile /etc/letsencrypt/live/relay.yourdomain.com/privkey.pem
|
||||
|
||||
# WebSocket proxy
|
||||
ProxyPreserveHost On
|
||||
ProxyRequests Off
|
||||
ProxyPass / ws://127.0.0.1:8888/
|
||||
ProxyPassReverse / ws://127.0.0.1:8888/
|
||||
|
||||
# Fallback for HTTP requests
|
||||
RewriteEngine on
|
||||
RewriteCond %{HTTP:Upgrade} websocket [NC]
|
||||
RewriteCond %{HTTP:Connection} upgrade [NC]
|
||||
RewriteRule ^/?(.*) "ws://127.0.0.1:8888/$1" [P,L]
|
||||
|
||||
# Security headers
|
||||
Header always set Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
|
||||
Header always set X-Content-Type-Options nosniff
|
||||
Header always set X-Frame-Options DENY
|
||||
</VirtualHost>
|
||||
|
||||
<VirtualHost *:80>
|
||||
ServerName relay.yourdomain.com
|
||||
Redirect permanent / https://relay.yourdomain.com/
|
||||
</VirtualHost>
|
||||
```
|
||||
|
||||
## Monitoring Setup
|
||||
|
||||
### System Monitoring
|
||||
|
||||
#### Basic Monitoring Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /usr/local/bin/relay-monitor.sh
|
||||
|
||||
LOG_FILE="/var/log/relay-monitor.log"
|
||||
DATE=$(date '+%Y-%m-%d %H:%M:%S')
|
||||
|
||||
# Check if relay is running
|
||||
if ! pgrep -f "c_relay_x86" > /dev/null; then
|
||||
echo "[$DATE] ERROR: Relay process not running" >> $LOG_FILE
|
||||
systemctl restart c-relay
|
||||
fi
|
||||
|
||||
# Check port availability
|
||||
if ! netstat -tln | grep -q ":8888"; then
|
||||
echo "[$DATE] ERROR: Port 8888 not listening" >> $LOG_FILE
|
||||
fi
|
||||
|
||||
# Check database file
|
||||
RELAY_DB=$(find /opt/c-relay -name "*.nrdb" | head -1)
|
||||
if [[ -n "$RELAY_DB" ]]; then
|
||||
DB_SIZE=$(du -h "$RELAY_DB" | cut -f1)
|
||||
echo "[$DATE] INFO: Database size: $DB_SIZE" >> $LOG_FILE
|
||||
fi
|
||||
|
||||
# Check memory usage
|
||||
MEM_USAGE=$(ps aux | grep c_relay_x86 | grep -v grep | awk '{print $6}')
|
||||
if [[ -n "$MEM_USAGE" ]]; then
|
||||
echo "[$DATE] INFO: Memory usage: ${MEM_USAGE}KB" >> $LOG_FILE
|
||||
fi
|
||||
```
|
||||
|
||||
#### Cron Job Setup
|
||||
```bash
|
||||
# Add to crontab
|
||||
echo "*/5 * * * * /usr/local/bin/relay-monitor.sh" | sudo crontab -
|
||||
|
||||
# Make script executable
|
||||
sudo chmod +x /usr/local/bin/relay-monitor.sh
|
||||
```
|
||||
|
||||
### Log Aggregation
|
||||
|
||||
#### Centralized Logging with rsyslog
|
||||
```bash
|
||||
# /etc/rsyslog.d/50-c-relay.conf
|
||||
if $programname == 'c-relay' then /var/log/c-relay.log
|
||||
& stop
|
||||
```
|
||||
|
||||
### External Monitoring
|
||||
|
||||
#### Prometheus Integration
|
||||
```yaml
|
||||
# /etc/prometheus/prometheus.yml
|
||||
scrape_configs:
|
||||
- job_name: 'c-relay'
|
||||
static_configs:
|
||||
- targets: ['localhost:8888']
|
||||
metrics_path: '/metrics' # If implemented
|
||||
scrape_interval: 30s
|
||||
```
|
||||
|
||||
## Security Hardening
|
||||
|
||||
### System Hardening
|
||||
|
||||
#### Service User Restrictions
|
||||
```bash
|
||||
# Restrict service user
|
||||
sudo usermod -s /bin/false c-relay
|
||||
sudo usermod -d /opt/c-relay c-relay
|
||||
|
||||
# Set proper permissions
|
||||
sudo chmod 700 /opt/c-relay
|
||||
sudo chown -R c-relay:c-relay /opt/c-relay
|
||||
```
|
||||
|
||||
#### File System Restrictions
|
||||
```bash
|
||||
# Mount data directory with appropriate options
|
||||
echo "/dev/sdb /opt/c-relay ext4 defaults,noexec,nosuid,nodev 0 2" >> /etc/fstab
|
||||
```
|
||||
|
||||
### Network Security
|
||||
|
||||
#### Fail2Ban Configuration
|
||||
```ini
|
||||
# /etc/fail2ban/jail.d/c-relay.conf
|
||||
[c-relay-dos]
|
||||
enabled = true
|
||||
port = 8888
|
||||
filter = c-relay-dos
|
||||
logpath = /var/log/c-relay.log
|
||||
maxretry = 10
|
||||
findtime = 60
|
||||
bantime = 300
|
||||
```
|
||||
|
||||
#### DDoS Protection
|
||||
```bash
|
||||
# iptables rate limiting
|
||||
sudo iptables -A INPUT -p tcp --dport 8888 -m limit --limit 25/minute --limit-burst 100 -j ACCEPT
|
||||
sudo iptables -A INPUT -p tcp --dport 8888 -j DROP
|
||||
```
|
||||
|
||||
### Database Security
|
||||
|
||||
#### Encryption at Rest
|
||||
```bash
|
||||
# Use encrypted filesystem
|
||||
sudo cryptsetup luksFormat /dev/sdb
|
||||
sudo cryptsetup luksOpen /dev/sdb relay-data
|
||||
sudo mkfs.ext4 /dev/mapper/relay-data
|
||||
```
|
||||
|
||||
## Backup and Recovery
|
||||
|
||||
### Automated Backup
|
||||
|
||||
#### Database Backup Script
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# /usr/local/bin/backup-relay.sh
|
||||
|
||||
BACKUP_DIR="/backup/c-relay"
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
RELAY_DB=$(find /opt/c-relay -name "*.nrdb" | head -1)
|
||||
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
if [[ -n "$RELAY_DB" ]]; then
|
||||
# SQLite backup
|
||||
sqlite3 "$RELAY_DB" ".backup $BACKUP_DIR/relay_backup_$DATE.nrdb"
|
||||
|
||||
# Compress backup
|
||||
gzip "$BACKUP_DIR/relay_backup_$DATE.nrdb"
|
||||
|
||||
# Cleanup old backups (keep 30 days)
|
||||
find "$BACKUP_DIR" -name "relay_backup_*.nrdb.gz" -mtime +30 -delete
|
||||
|
||||
echo "Backup completed: relay_backup_$DATE.nrdb.gz"
|
||||
else
|
||||
echo "No relay database found!"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### Cron Schedule
|
||||
```bash
|
||||
# Daily backup at 2 AM
|
||||
echo "0 2 * * * /usr/local/bin/backup-relay.sh" | sudo crontab -
|
||||
```
|
||||
|
||||
### Cloud Backup
|
||||
|
||||
#### AWS S3 Sync
|
||||
```bash
|
||||
# Install AWS CLI
|
||||
sudo apt install -y awscli
|
||||
|
||||
# Configure AWS credentials
|
||||
aws configure
|
||||
|
||||
# Sync backups to S3
|
||||
aws s3 sync /backup/c-relay/ s3://your-backup-bucket/c-relay/ --delete
|
||||
```
|
||||
|
||||
### Disaster Recovery
|
||||
|
||||
#### Recovery Procedures
|
||||
```bash
|
||||
# 1. Restore from backup
|
||||
gunzip backup/relay_backup_20231201_020000.nrdb.gz
|
||||
cp backup/relay_backup_20231201_020000.nrdb /opt/c-relay/
|
||||
|
||||
# 2. Fix permissions
|
||||
sudo chown c-relay:c-relay /opt/c-relay/*.nrdb
|
||||
|
||||
# 3. Restart service
|
||||
sudo systemctl restart c-relay
|
||||
|
||||
# 4. Verify recovery
|
||||
sudo journalctl -u c-relay --since "1 minute ago"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
This deployment guide provides comprehensive coverage for deploying the C Nostr Relay across various environments while taking full advantage of the event-based configuration system's simplicity and security features.
|
||||
Reference in New Issue
Block a user