Server Management

Server management is the foundation of Supascale's infrastructure management platform. This guide covers registering servers, monitoring their health, managing API keys, and configuring server-specific settings.

Overview

Supascale manages your infrastructure through lightweight agents installed on your servers. Each server:

• Runs the Supascale agent for communication
• Can host multiple Supabase instances
• Reports real-time metrics and status
• Executes commands sent from the dashboard

Adding Servers

Server Registration

1. Navigate to Servers

   • Go to Dashboard → Servers
   • Click "Add Server"

2. Generate Registration Command

   • Enter a descriptive server name
   • Copy the generated installation command
   • The command includes a unique API key for this server

3. Install Agent on Server

   # Example registration command
   curl -fsSL https://install.supascale.io | bash -s -- \
     --api-key="sk_live_abc123..." \
     --server-name="production-web-01"
   

4. Verify Registration

   • Server appears in dashboard within 60 seconds
   • Status shows as "Online" with green indicator
   • Basic system information is displayed

Server Naming Conventions

Use clear, descriptive names for easy identification:

Environment-Purpose-Number
├── production-web-01
├── production-db-01
├── staging-app-01
├── development-test-01
└── backup-storage-01

Server Status and Health

Status Indicators

Online (Green): Agent is running and communicating normally

• Last seen: < 2 minutes ago
• All systems operational
• Ready to receive commands

Degraded (Yellow): Server experiencing minor issues

• High resource usage (>90% CPU/memory)
• Disk space running low (<10% free)
• Network latency issues

Offline (Red): Agent not responding

• Last seen: > 5 minutes ago
• Server may be down or network issues
• Automatic retry attempts in progress

Error (Red): Server experiencing critical issues

• Agent crashed or failed to start
• Docker service unavailable
• Permission or configuration errors

Health Monitoring

Real-time Metrics:

• CPU usage percentage
• Memory usage and available
• Disk usage across all mounted volumes
• Network I/O rates
• Load average
• Active Docker containers

Historical Data:

• 24-hour metric trends
• Performance baselines
• Anomaly detection
• Capacity planning insights

Server Configuration

Basic Settings

Server Name: Descriptive identifier for the dashboard

# Update server name
supascale-agent config set name "new-server-name"

Resource Limits: Control resource allocation

# /etc/supascale/config.yaml
resource_limits:
  max_instances: 5
  max_memory_per_instance: "4G"
  max_cpu_per_instance: 2.0

Auto-start Behavior: Control instance startup

auto_start:
  enabled: true
  delay: 30s  # Wait 30s after boot before starting instances
  order: "creation"  # or "priority", "name"

Network Configuration

Port Allocation: Configure port ranges for instances

ports:
  base_range: 54000
  max_range: 65000
  increment: 10  # Reserve 10 ports per instance

Firewall Integration: Automatic firewall rules

firewall:
  auto_configure: true
  tool: "ufw"  # or "iptables", "firewalld"
  allow_external: true  # Allow external access to instances

API Key Management

Server API Keys

Each server has a unique API key for authentication:

1. View Current Key

   • Go to Server → Settings → API Keys
   • Keys are displayed with masked values for security

2. Regenerate API Key

   • Click "Regenerate Key"
   • Update agent configuration with new key
   • Old key is immediately invalidated

3. Key Rotation Schedule

   • Recommended: Rotate keys every 90 days
   • Set calendar reminders for rotation
   • Use automated tools for enterprise environments

API Key Security

Best Practices:

• Store keys securely in configuration files
• Use environment variables where possible
• Restrict file permissions (600)
• Monitor key usage and access patterns

Emergency Procedures:

• Compromised keys can be revoked instantly
• New keys are generated immediately
• Agent automatically reconnects with new key

Server Actions

Remote Commands

Execute commands on servers directly from the dashboard:

System Commands:

• Restart agent
• Update agent version
• View system information
• Check Docker status

Instance Management:

• Start/stop all instances
• Restart specific instances
• View instance logs
• Update instance configurations

Bulk Operations

Manage multiple servers simultaneously:

1. Select Multiple Servers

   • Use checkboxes to select servers
   • Filter by status, environment, or tags

2. Available Bulk Actions:

   • Update agent versions
   • Apply configuration changes
   • Restart services
   • Generate health reports

Server Maintenance

Planned Maintenance

1. Enable Maintenance Mode

   • Prevents new instance deployments
   • Displays maintenance notice
   • Preserves running instances

2. Maintenance Tasks:

   • OS updates and patches
   • Docker version updates
   • Hardware maintenance
   • Network configuration changes

3. Exit Maintenance Mode

   • Re-enable instance management
   • Resume monitoring and alerts
   • Verify all systems operational

Agent Updates

Automatic Updates (Recommended):

# Enable automatic agent updates
auto_update:
  enabled: true
  channel: "stable"  # or "beta", "latest"
  schedule: "0 2 * * 0"  # Weekly on Sunday at 2 AM

Manual Updates:

# Update agent to latest version
sudo supascale-agent update

# Update to specific version
sudo supascale-agent update --version "v1.2.3"

# Check for available updates
sudo supascale-agent check-update

Monitoring and Alerts

Server-Level Alerts

Configure alerts for server health issues:

CPU Usage Alert:

• Trigger: CPU usage > 90% for 5 minutes
• Actions: Email notification, Slack message
• Auto-resolution when CPU < 80%

Memory Usage Alert:

• Trigger: Memory usage > 95% for 2 minutes
• Actions: Email + webhook notification
• Escalation: Page on-call engineer

Disk Space Alert:

• Trigger: Disk usage > 90%
• Actions: Immediate notification
• Suggested: Clean up logs, expand storage

Agent Disconnection Alert:

• Trigger: Agent offline > 5 minutes
• Actions: Multiple notification channels
• Auto-retry: Attempt reconnection

Performance Baselines

Supascale automatically establishes performance baselines:

• CPU Usage Patterns: Normal daily/weekly cycles
• Memory Consumption: Typical usage for your workload
• Network Traffic: Expected I/O patterns
• Instance Load: Performance under normal conditions

Troubleshooting

Common Issues

Server Shows Offline:

1. Check agent service status: sudo systemctl status supascale-agent
2. Verify network connectivity: ping api.supascale.io
3. Check firewall rules: sudo ufw status
4. Review agent logs: sudo journalctl -u supascale-agent -f

High Resource Usage:

1. Identify resource-intensive processes: htop
2. Check running instances: docker ps
3. Review instance resource limits
4. Consider scaling up server or distributing load

Permission Errors:

1. Verify agent user permissions: id supascale
2. Check Docker group membership: groups supascale
3. Verify file permissions: ls -la /etc/supascale/
4. Check sudo configuration if needed

Performance Optimization

Resource Allocation:

• Monitor instance resource usage
• Adjust resource limits based on actual usage
• Consider server upgrades for consistent high usage

Network Optimization:

• Use local DNS for faster resolution
• Configure connection pooling
• Monitor bandwidth usage

Storage Optimization:

• Use SSD storage for better performance
• Implement log rotation
• Regular cleanup of unused Docker images

Security

Server Hardening

System Security:

• Keep OS updated with latest patches
• Configure firewall rules
• Disable unnecessary services
• Use SSH key authentication

Supascale-Specific Security:

• Rotate API keys regularly
• Monitor agent logs for suspicious activity
• Restrict network access to necessary ports
• Use HTTPS for all communication

Compliance

Data Protection:

• Instance data remains on your servers
• API communication is encrypted
• Audit logs track all administrative actions
• Backup encryption for sensitive data

Access Control:

• Role-based access to server management
• API key scoping and limitations
• Activity logging and monitoring
• Regular access reviews

Next: Learn about Instance Management to start deploying Supabase instances.