Setup Cosmos RPC Node with Nginx Reverse Proxy on Linux

Introduction

This guide will walk you through setting up a Cosmos RPC node with Nginx as a reverse proxy on Linux. This setup provides better security, SSL/TLS support, and load balancing capabilities.

Prerequisites

Ubuntu 20.04 or 22.04 LTS (or similar Linux distribution)
Root or sudo access
Domain name pointed to your server (optional, for SSL)
At least 4GB RAM and 200GB SSD storage
Basic knowledge of Linux command line

Architecture Overview

Internet → Nginx (Port 80/443) → Cosmos RPC (Port 26657)
                                → Cosmos API (Port 1317)
                                → gRPC (Port 9090)

Step 1: Update System

# Update package list
sudo apt update && sudo apt upgrade -y

# Install essential tools
sudo apt install -y curl wget git build-essential jq

Step 2: Install Go

Cosmos SDK requires Go 1.21 or higher.

# Download Go
cd $HOME
wget https://go.dev/dl/go1.21.6.linux-amd64.tar.gz

# Extract and install
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.21.6.linux-amd64.tar.gz

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

# Verify installation
go version

Step 3: Install Cosmos Node

For this example, we'll use Cosmos Hub (gaiad):

# Clone repository
cd $HOME
git clone https://github.com/cosmos/gaia.git
cd gaia

# Checkout latest version
git checkout v14.1.0

# Build
make install

# Verify installation
gaiad version

Step 4: Initialize Node

# Initialize node
gaiad init <your-moniker> --chain-id cosmoshub-4

# Download genesis
wget -O ~/.gaia/config/genesis.json https://github.com/cosmos/mainnet/raw/master/genesis/genesis.cosmoshub-4.json.gz
gunzip ~/.gaia/config/genesis.json.gz

# Configure seeds and peers
SEEDS="ade4d8bc8cbe014af6ebdf3cb7b1e9ad36f412c0@seeds.polkachu.com:14956"
PEERS="see https://polkachu.com/live_peers/cosmos for updated peers"

sed -i.bak -e "s/^seeds *=.*/seeds = \"$SEEDS\"/" ~/.gaia/config/config.toml
sed -i.bak -e "s/^persistent_peers *=.*/persistent_peers = \"$PEERS\"/" ~/.gaia/config/config.toml

Step 5: Configure RPC Settings

Edit ~/.gaia/config/config.toml:

# Enable RPC
sed -i 's/laddr = "tcp:\/\/127.0.0.1:26657"/laddr = "tcp:\/\/0.0.0.0:26657"/' ~/.gaia/config/config.toml

# Enable CORS (if needed)
sed -i 's/cors_allowed_origins = \[\]/cors_allowed_origins = \["*"\]/' ~/.gaia/config/config.toml

# Set max connections
sed -i 's/max_open_connections = 900/max_open_connections = 2000/' ~/.gaia/config/config.toml

Edit ~/.gaia/config/app.toml:

# Enable API
sed -i 's/enable = false/enable = true/' ~/.gaia/config/app.toml
sed -i 's/swagger = false/swagger = true/' ~/.gaia/config/app.toml

# Enable gRPC
sed -i 's/address = "0.0.0.0:9090"/address = "0.0.0.0:9090"/' ~/.gaia/config/app.toml

Step 6: Create Systemd Service

sudo tee /etc/systemd/system/gaiad.service > /dev/null <<EOF
[Unit]
Description=Cosmos Hub Node
After=network-online.target

[Service]
User=$USER
ExecStart=$(which gaiad) start
Restart=on-failure
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
EOF

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable gaiad
sudo systemctl start gaiad

# Check status
sudo systemctl status gaiad

# View logs
sudo journalctl -u gaiad -f

Step 7: Install Nginx

# Install Nginx
sudo apt install -y nginx

# Start and enable Nginx
sudo systemctl start nginx
sudo systemctl enable nginx

# Check status
sudo systemctl status nginx

Step 8: Configure Nginx Reverse Proxy

Create Nginx configuration:

sudo tee /etc/nginx/sites-available/cosmos-rpc > /dev/null <<'EOF'
# Rate limiting
limit_req_zone $binary_remote_addr zone=rpc_limit:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=api_limit:10m rate=20r/s;

# Upstream servers
upstream cosmos_rpc {
    server 127.0.0.1:26657;
    keepalive 32;
}

upstream cosmos_api {
    server 127.0.0.1:1317;
    keepalive 32;
}

upstream cosmos_grpc {
    server 127.0.0.1:9090;
    keepalive 32;
}

# HTTP Server (redirect to HTTPS)
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        return 301 https://$server_name$request_uri;
    }
}

# HTTPS Server
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL Configuration (will be added by Certbot)
    # ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;

    # RPC endpoint
    location /rpc/ {
        limit_req zone=rpc_limit burst=20 nodelay;
        
        proxy_pass http://cosmos_rpc/;
        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;
        
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # API endpoint
    location /api/ {
        limit_req zone=api_limit burst=40 nodelay;
        
        proxy_pass http://cosmos_api/;
        proxy_http_version 1.1;
        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;
    }

    # gRPC endpoint
    location /grpc/ {
        grpc_pass grpc://cosmos_grpc;
        grpc_set_header Host $host;
        grpc_set_header X-Real-IP $remote_addr;
    }

    # Health check
    location /health {
        access_log off;
        return 200 "OK\n";
        add_header Content-Type text/plain;
    }
}
EOF

# Enable site
sudo ln -s /etc/nginx/sites-available/cosmos-rpc /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Reload Nginx
sudo systemctl reload nginx

Step 9: Install SSL Certificate (Optional but Recommended)

# Install Certbot
sudo apt install -y certbot python3-certbot-nginx

# Get SSL certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal is configured automatically
# Test renewal
sudo certbot renew --dry-run

Step 10: Configure Firewall

# Install UFW if not installed
sudo apt install -y ufw

# Allow SSH
sudo ufw allow 22/tcp

# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Allow P2P (Cosmos)
sudo ufw allow 26656/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

Step 11: Monitoring and Optimization

Enable Prometheus Metrics

Edit ~/.gaia/config/config.toml:

sed -i 's/prometheus = false/prometheus = true/' ~/.gaia/config/config.toml
sed -i 's/prometheus_listen_addr = ":26660"/prometheus_listen_addr = "127.0.0.1:26660"/' ~/.gaia/config/config.toml

Add Nginx Monitoring Location

Add to your Nginx config:

location /metrics {
    proxy_pass http://127.0.0.1:26660/metrics;
    allow 127.0.0.1;
    deny all;
}

System Optimization

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

# Optimize network settings
sudo tee -a /etc/sysctl.conf > /dev/null <<EOF
net.core.rmem_max = 134217728
net.core.wmem_max = 134217728
net.ipv4.tcp_rmem = 4096 87380 67108864
net.ipv4.tcp_wmem = 4096 65536 67108864
net.ipv4.tcp_congestion_control = bbr
EOF

sudo sysctl -p

Step 12: Testing Your RPC Node

# Test RPC endpoint
curl https://your-domain.com/rpc/status

# Test API endpoint
curl https://your-domain.com/api/cosmos/base/tendermint/v1beta1/node_info

# Test from remote
curl -X POST https://your-domain.com/rpc/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"status","params":[]}'

Maintenance

View Logs

# Cosmos node logs
sudo journalctl -u gaiad -f

# Nginx access logs
sudo tail -f /var/log/nginx/access.log

# Nginx error logs
sudo tail -f /var/log/nginx/error.log

Update Node

# Stop service
sudo systemctl stop gaiad

# Update code
cd ~/gaia
git fetch --all
git checkout v15.0.0  # new version

# Rebuild
make install

# Restart service
sudo systemctl start gaiad

Backup Configuration

# Backup important files
tar -czf cosmos-backup-$(date +%Y%m%d).tar.gz \
  ~/.gaia/config/ \
  ~/.gaia/data/priv_validator_state.json \
  /etc/nginx/sites-available/cosmos-rpc

Troubleshooting

Node Not Syncing

# Check peers
gaiad status | jq .SyncInfo

# Add more peers
# Visit https://polkachu.com/live_peers/cosmos

Nginx 502 Bad Gateway

# Check if node is running
sudo systemctl status gaiad

# Check if ports are listening
sudo netstat -tulpn | grep -E '26657|1317|9090'

# Check Nginx error logs
sudo tail -f /var/log/nginx/error.log

High Memory Usage

# Check memory
free -h

# Restart node
sudo systemctl restart gaiad

# Consider adding swap
sudo fallocate -l 8G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Security Best Practices

Keep System Updated: Regularly update OS and packages
Use Firewall: Only open necessary ports
Enable SSL: Always use HTTPS for public endpoints
Rate Limiting: Protect against DDoS with Nginx rate limits
Monitor Logs: Regularly check for suspicious activity
Backup Keys: Keep validator keys in secure, offline storage
Use Strong Passwords: For all accounts and services
Enable Fail2ban: Protect against brute force attacks

Performance Tuning

For High Traffic

# In Nginx config
worker_processes auto;
worker_rlimit_nofile 65535;

events {
    worker_connections 4096;
    use epoll;
    multi_accept on;
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    keepalive_requests 100;
}

For Cosmos Node

# In config.toml
[rpc]
max_open_connections = 2000
max_subscription_clients = 100
max_subscriptions_per_client = 5

Conclusion

You now have a production-ready Cosmos RPC node with Nginx reverse proxy. This setup provides:

✅ SSL/TLS encryption
✅ Rate limiting protection
✅ Load balancing capability
✅ Professional endpoint structure
✅ Monitoring and logging
✅ Security hardening

Additional Resources

Support

Need help? Contact us: