Agent Installation

The Supascale agent is a lightweight Go application that runs on your servers to manage Supabase instances. This guide covers installation, configuration, and troubleshooting.

System Requirements

Minimum Requirements

• OS: Linux (Ubuntu 18.04+, CentOS 7+, Debian 9+)
• RAM: 2 GB available
• CPU: 2 cores
• Disk: 20 GB free space
• Network: Internet connectivity for API communication

Required Software

• Docker: Version 20.10+
• Docker Compose: Version 2.0+
• curl: For downloading the agent
• sudo: Administrative privileges

Recommended Setup

• RAM: 4+ GB for production workloads
• CPU: 4+ cores for multiple instances
• Disk: SSD storage with 50+ GB
• Network: Stable internet connection

Pre-Installation Setup

Install Docker

Ubuntu/Debian:

# Update package list
sudo apt update

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Verify installation
docker --version
docker-compose --version

CentOS/RHEL:

# Install Docker
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker
sudo systemctl enable docker

# Add user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Configure Firewall

The agent needs to communicate with Supascale and serve instances:

# Allow Supascale API communication (HTTPS)
sudo ufw allow 443/tcp

# Allow SSH access
sudo ufw allow 22/tcp

# Allow Supabase instance ports (54000-65000 range)
sudo ufw allow 54000:65000/tcp

# Enable firewall
sudo ufw enable

Agent Installation

Download and Install

1. Get Installation Script

   curl -fsSL https://install.supascale.io -o install-agent.sh
   chmod +x install-agent.sh
   

2. Run Installation

   sudo ./install-agent.sh
   

3. Verify Installation

   # Check if agent is running
   sudo systemctl status supascale-agent
   
   # View agent logs
   sudo journalctl -u supascale-agent -f
   

Manual Installation

If you prefer manual installation:

1. Download Agent Binary

   # Download for Linux x64
   curl -L https://releases.supascale.io/agent/latest/supascale-agent-linux-amd64 -o supascale-agent
   chmod +x supascale-agent
   sudo mv supascale-agent /usr/local/bin/
   

2. Create Service User

   sudo useradd --system --no-create-home --shell /bin/false supascale
   

3. Create Directories

   sudo mkdir -p /etc/supascale
   sudo mkdir -p /var/lib/supascale
   sudo mkdir -p /var/log/supascale
   sudo chown supascale:supascale /var/lib/supascale /var/log/supascale
   

4. Create systemd Service

   sudo tee /etc/systemd/system/supascale-agent.service > /dev/null <<EOF
   [Unit]
   Description=Supascale Agent
   After=network.target docker.service
   Requires=docker.service
   
   [Service]
   Type=simple
   User=supascale
   ExecStart=/usr/local/bin/supascale-agent
   Restart=always
   RestartSec=5
   WorkingDirectory=/var/lib/supascale
   StandardOutput=journal
   StandardError=journal
   
   [Install]
   WantedBy=multi-user.target
   EOF
   

Configuration

Initial Configuration

1. Get API Key from Dashboard

   • Log into your Supascale dashboard
   • Navigate to Servers → Add Server
   • Copy the provided API key and server registration command

2. Configure Agent

   # Create configuration file
   sudo tee /etc/supascale/config.yaml > /dev/null <<EOF
   api_url: "https://api.supascale.io"
   server_id: ""  # Will be set during registration
   api_key: "your-api-key-here"
   poll_interval: 30s
   log_level: "info"
   data_dir: "/var/lib/supascale"
   
   # Resource monitoring
   monitoring:
     enabled: true
     interval: 60s
   
   # Auto-start instances on boot
   auto_start: true
   EOF
   

3. Set Permissions

   sudo chown supascale:supascale /etc/supascale/config.yaml
   sudo chmod 600 /etc/supascale/config.yaml
   

Advanced Configuration

Custom Data Directory:

# Use custom directory for instance data
data_dir: "/opt/supascale-data"

# Ensure directory exists and has correct permissions
# sudo mkdir -p /opt/supascale-data
# sudo chown supascale:supascale /opt/supascale-data

Resource Limits:

# Set resource limits for instances
resource_limits:
  max_instances: 10
  max_memory_per_instance: "2G"
  max_cpu_per_instance: 2.0

Logging Configuration:

logging:
  level: "info"  # debug, info, warn, error
  format: "json"  # json or text
  output: "/var/log/supascale/agent.log"
  max_size: 100  # MB
  max_backups: 5

Starting the Agent

Enable and Start Service

# Reload systemd
sudo systemctl daemon-reload

# Enable auto-start
sudo systemctl enable supascale-agent

# Start the agent
sudo systemctl start supascale-agent

# Check status
sudo systemctl status supascale-agent

Verify Agent Communication

1. Check Logs

   # View recent logs
   sudo journalctl -u supascale-agent -n 50
   
   # Follow logs in real-time
   sudo journalctl -u supascale-agent -f
   

2. Expected Log Messages

   INFO Agent starting up...
   INFO Connecting to Supascale API...
   INFO Agent registered successfully
   INFO Polling for commands every 30s
   INFO Resource monitoring enabled
   

Server Registration

After installation, register your server with Supascale:

1. Auto-Registration

   • The agent automatically registers using the API key
   • Check your dashboard to see the new server

2. Manual Registration (if needed)

   # Register server with custom name
   sudo supascale-agent register --name "production-server-01"
   

3. Verify Registration

   • Server should appear in your Supascale dashboard
   • Status should show as "Online"
   • Resources should be reporting

Troubleshooting

Common Issues

Agent Won't Start

# Check system logs
sudo journalctl -u supascale-agent -n 50

# Verify configuration
sudo supascale-agent config validate

# Check file permissions
ls -la /etc/supascale/config.yaml

Connection Issues

# Test API connectivity
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.supascale.io/health

# Check firewall
sudo ufw status
sudo iptables -L

# Verify DNS resolution
nslookup api.supascale.io

Docker Issues

# Verify Docker is running
sudo systemctl status docker

# Test Docker permissions
docker ps

# Check Docker version
docker --version
docker-compose --version

Log Analysis

Increase Log Verbosity

# In /etc/supascale/config.yaml
log_level: "debug"

Common Error Messages

• "connection refused": Network/firewall issue
• "authentication failed": Invalid API key
• "docker not found": Docker not installed or not in PATH
• "permission denied": User permissions issue

Performance Optimization

Resource Monitoring

# Check agent resource usage
ps aux | grep supascale-agent
top -p $(pgrep supascale-agent)

# Monitor system resources
htop
iostat -x 1

Agent Updates

# Update to latest version
sudo supascale-agent update

# Or download manually
curl -L https://releases.supascale.io/agent/latest/supascale-agent-linux-amd64 -o supascale-agent
sudo systemctl stop supascale-agent
sudo mv supascale-agent /usr/local/bin/
sudo chmod +x /usr/local/bin/supascale-agent
sudo systemctl start supascale-agent

Security Considerations

API Key Security

• Store API keys securely
• Rotate keys regularly
• Use environment variables for sensitive data
• Monitor key usage in dashboard

Network Security

• Use HTTPS for all communication
• Implement proper firewall rules
• Consider VPN for additional security
• Monitor network traffic

File Permissions

• Restrict config file access (600)
• Run agent as non-root user
• Secure data directories
• Regular security updates

Next: Register your server with Supascale.