Bare Metal Installation

This guide provides detailed instructions for installing Shugur Relay directly on a server without using Docker. This method is for advanced users who require maximum performance and control over their environment.

Prerequisites

System Requirements

Operating System: Ubuntu 22.04 LTS or newer (other Linux distributions may work)
CPU: 4 cores minimum (8+ cores recommended for production)
RAM: 8 GB minimum (16+ GB recommended for production)
Storage: 50 GB SSD minimum (NVMe recommended for production)

Software Dependencies

Go: Version 1.21 or newer
Database: CockroachDB 23.1+ (recommended) or PostgreSQL 13+
Git, curl, wget, openssl
systemd (for service management)

Installation Steps

1. Install Go

# Download and install Go 1.24
cd /tmp
wget https://go.dev/dl/go1.24.1.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.1.linux-amd64.tar.gz

# Add Go to PATH
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# Verify installation
go version

2. Install Database

Option A: CockroachDB (Recommended)

cd /tmp
wget https://binaries.cockroachdb.com/cockroach-v24.1.5.linux-amd64.tgz
tar -xzf cockroach-v24.1.5.linux-amd64.tgz
sudo cp cockroach-v24.1.5.linux-amd64/cockroach /usr/local/bin/
sudo chmod +x /usr/local/bin/cockroach
cockroach version

Option B: PostgreSQL (Alternative)

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install postgresql postgresql-contrib

# Start PostgreSQL
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql -c "CREATE DATABASE shugur_relay;"
sudo -u postgres psql -c "CREATE USER relay_user WITH PASSWORD 'your_secure_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE shugur_relay TO relay_user;"

3. Create System Users

# For CockroachDB (if using Option A)
sudo useradd --system --shell /bin/bash --home /var/lib/cockroach cockroach

# For Shugur Relay
sudo useradd --system --shell /bin/bash --home /opt/shugur-relay shugur

4. Database Setup

For CockroachDB (Option A)

sudo mkdir -p /var/lib/cockroach/{data,certs}
sudo chown cockroach:cockroach /var/lib/cockroach/{data,certs}

sudo -u cockroach cockroach cert create-ca --certs-dir=/var/lib/cockroach/certs --ca-key=/var/lib/cockroach/certs/ca.key
sudo -u cockroach cockroach cert create-node localhost $(hostname) --certs-dir=/var/lib/cockroach/certs --ca-key=/var/lib/cockroach/certs/ca.key
sudo -u cockroach cockroach cert create-client root --certs-dir=/var/lib/cockroach/certs --ca-key=/var/lib/cockroach/certs/ca.key
sudo -u cockroach cockroach cert create-client relay --certs-dir=/var/lib/cockroach/certs --ca-key=/var/lib/cockroach/certs/ca.key

sudo tee /etc/systemd/system/cockroachdb.service > /dev/null <<EOF
[Unit]
Description=CockroachDB
After=network.target

[Service]
Type=exec
User=cockroach
ExecStart=/usr/local/bin/cockroach start --certs-dir=/var/lib/cockroach/certs --store=/var/lib/cockroach/data --listen-addr=localhost:26257 --http-addr=localhost:8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable cockroachdb
sudo systemctl start cockroachdb

sudo -u cockroach cockroach init --certs-dir=/var/lib/cockroach/certs --host=localhost:26257

For PostgreSQL (Option B)

If you chose PostgreSQL, the database is already set up. Skip to step 5.

5. Initialize Application Database

For CockroachDB:

sudo -u cockroach cockroach sql --certs-dir=/var/lib/cockroach/certs --host=localhost:26257 <<EOF
CREATE DATABASE IF NOT EXISTS shugur;
CREATE USER IF NOT EXISTS relay;
GRANT ALL ON DATABASE shugur TO relay;
EOF

For PostgreSQL:

# Database was already created in step 2, nothing additional needed
echo "PostgreSQL database already configured"

6. Build and Install Shugur Relay

cd /tmp
git clone https://github.com/Shugur-Network/Relay.git
cd Relay
go build -ldflags "-w -s -X main.version=$(cat VERSION) -X main.commit=$(git rev-parse --short HEAD) -X main.date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" -o shugur-relay ./cmd

sudo cp shugur-relay /usr/local/bin/
sudo chmod +x /usr/local/bin/shugur-relay

sudo mkdir -p /opt/shugur-relay/{config,logs,certs}
sudo chown shugur:shugur /opt/shugur-relay

sudo cp /var/lib/cockroach/certs/{ca.crt,client.relay.crt,client.relay.key} /opt/shugur-relay/certs/
sudo chown shugur:shugur /opt/shugur-relay/certs/*
sudo chmod 600 /opt/shugur-relay/certs/*.key

7. Configure Shugur Relay

Option A: YAML Configuration (Recommended)

sudo -u shugur tee /opt/shugur-relay/config/config.yaml > /dev/null <<EOF
GENERAL: {}

LOGGING:
  LEVEL: info
  FILE: /opt/shugur-relay/logs/relay.log
  FORMAT: json
  MAX_SIZE: 100
  MAX_BACKUPS: 5
  MAX_AGE: 30

METRICS:
  ENABLED: true
  PORT: 2112

DATABASE:
  SERVER: localhost
  PORT: 26257

RELAY:
  NAME: "shugur-relay"
  DESCRIPTION: "High-performance, reliable, and scalable Nostr relay"
  CONTACT: "admin@example.com"
  ICON: "https://avatars.githubusercontent.com/u/198367099?s=400&u=2bc76d4fe6f57a1c39ef00fd784dd0bf85d79bda&v=4"
  BANNER: "https://github.com/Shugur-Network/relay/raw/main/banner.png"
  WS_ADDR: ":8080"
  PUBLIC_URL: "ws://localhost:8080"
  EVENT_CACHE_SIZE: 10000
  SEND_BUFFER_SIZE: 8192
  WRITE_TIMEOUT: 60s
  THROTTLING:
    MAX_CONTENT_LENGTH: 8192
    MAX_CONNECTIONS: 1000
    BAN_THRESHOLD: 10
    BAN_DURATION: 300
    RATE_LIMIT:
      ENABLED: true
      MAX_EVENTS_PER_SECOND: 10
      MAX_REQUESTS_PER_SECOND: 20
      BURST_SIZE: 5
      PROGRESSIVE_BAN: true
      MAX_BAN_DURATION: 24h

RELAY_POLICY:
  BLACKLIST:
    PUBKEYS: []
  WHITELIST:
    PUBKEYS: []
EOF

Option B: Environment Variables

# Create environment file
sudo -u shugur tee /opt/shugur-relay/.env > /dev/null <<EOF
SHUGUR_RELAY_NAME="shugur-relay"
SHUGUR_RELAY_WS_ADDR=":8080"
SHUGUR_DATABASE_SERVER="localhost"
SHUGUR_DATABASE_PORT="26257"
SHUGUR_LOGGING_LEVEL="info"
SHUGUR_RELAY_CONTACT="admin@example.com"
SHUGUR_RELAY_PUBLIC_URL="ws://localhost:8080"
EOF

8. Create Systemd Service

sudo tee /etc/systemd/system/shugur-relay.service > /dev/null <<EOF
[Unit]
Description=Shugur Relay - Nostr relay
After=network.target cockroachdb.service
Requires=cockroachdb.service

[Service]
Type=exec
User=shugur
WorkingDirectory=/opt/shugur-relay
ExecStart=/usr/local/bin/shugur-relay --config /opt/shugur-relay/config/config.yaml
Restart=always
RestartSec=5
Environment=HOME=/opt/shugur-relay

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable shugur-relay
sudo systemctl start shugur-relay

Verification

1. Check Service Status

# Check if services are running
sudo systemctl status cockroachdb
sudo systemctl status shugur-relay

# View logs
sudo journalctl -u shugur-relay -f

2. Test Relay Connection

# Check if relay is responding
curl -H "Accept: application/nostr+json" http://localhost:8080/

# Check metrics endpoint
curl http://localhost:2112/metrics

# View web dashboard (if available)
curl http://localhost:8080

3. Test WebSocket Connection

# Install wscat if not available
sudo npm install -g wscat

# Test WebSocket connection
echo '["REQ","test",{"kinds":[1],"limit":1}]' | wscat -c ws://localhost:8080

# Or interactive test
wscat -c ws://localhost:8080
# Then type: ["REQ","test",{}]

4. Database Connection Test

For CockroachDB:

sudo -u cockroach cockroach sql --certs-dir=/var/lib/cockroach/certs --host=localhost:26257 -e "SELECT version();"

For PostgreSQL:

sudo -u postgres psql shugur_relay -c "SELECT version();"

Troubleshooting

Common Issues

1. Database Connection Failed

CockroachDB:

# Check if CockroachDB is running
sudo systemctl status cockroachdb

# Check certificate permissions
ls -la /var/lib/cockroach/certs/

# Test database connection
sudo -u cockroach cockroach sql --certs-dir=/var/lib/cockroach/certs --host=localhost:26257 -e "SELECT 1;"

PostgreSQL:

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Test connection
sudo -u postgres psql -c "SELECT 1;"

2. Port Already in Use

# Check what's using port 8080
sudo netstat -tulpn | grep :8080
# or
sudo lsof -i :8080

# Change port in configuration file
sudo nano /opt/shugur-relay/config/config.yaml

3. Permission Denied

# Make sure relay binary is executable
sudo chmod +x /usr/local/bin/shugur-relay

# Check file permissions
ls -la /usr/local/bin/shugur-relay

# Check config file permissions
sudo chown shugur:shugur /opt/shugur-relay/config/config.yaml

4. Go Build Issues

# Check Go installation
go version

# Clean module cache
go clean -modcache

# Reinstall dependencies
cd /tmp/Relay && go mod download

Service Management

# Start services
sudo systemctl start cockroachdb
sudo systemctl start shugur-relay

# Stop services
sudo systemctl stop shugur-relay
sudo systemctl stop cockroachdb

# Restart services
sudo systemctl restart shugur-relay

# Enable auto-start on boot
sudo systemctl enable cockroachdb
sudo systemctl enable shugur-relay

Performance Tuning

Database Optimization

CockroachDB Settings:

# Connect to CockroachDB and run optimization commands
sudo -u cockroach cockroach sql --certs-dir=/var/lib/cockroach/certs --host=localhost:26257 <<EOF
SET CLUSTER SETTING kv.range_split.by_load_enabled = true;
SET CLUSTER SETTING kv.range_split.load_qps_threshold = 2500;
EOF

PostgreSQL Settings:

# Edit PostgreSQL configuration
sudo nano /etc/postgresql/*/main/postgresql.conf

# Recommended settings for relay workload:
# shared_buffers = 256MB
# effective_cache_size = 1GB
# random_page_cost = 1.1
# checkpoint_completion_target = 0.9

Operating System Limits

# Increase file descriptor limits
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# Or for current session
ulimit -n 65536

# For systemd services, add to service file:
# LimitNOFILE=65536

Relay Configuration Tuning

# High-performance settings for /opt/shugur-relay/config/config.yaml
RELAY:
  EVENT_CACHE_SIZE: 50000      # Increase for more memory
  SEND_BUFFER_SIZE: 16384      # Increase for high throughput
  THROTTLING:
    MAX_CONNECTIONS: 2000      # Adjust based on server capacity
    MAX_EVENTS_PER_SECOND: 50  # Adjust based on requirements

Next Steps

After successful installation:

Configuration: Review the Configuration Guide for advanced settings
Monitoring: Set up monitoring using Prometheus metrics at :2112
Security: Configure firewall rules and SSL certificates for production
Backup: Set up automated database backups
Performance: Monitor and tune based on your workload

Getting Help

If you encounter issues:

Check the Troubleshooting Guide for more solutions
Review logs: sudo journalctl -u shugur-relay -f
Check the GitHub Issues page for known problems
Join the community discussions for support