Instance Deployment

Supascale makes deploying Supabase instances effortless with automated configuration, port management, and security setup. This guide covers the complete instance deployment process from creation to production readiness.

Overview

A Supabase instance in Supascale is a complete, isolated deployment that includes:

• PostgreSQL Database: High-performance database with extensions
• PostgREST API: Automatic REST API generation
• Realtime Server: WebSocket connections for live updates
• Authentication Service: User management and JWT tokens
• Storage Service: File upload and management
• Dashboard: Supabase Studio for administration
• Edge Functions: Serverless TypeScript/JavaScript runtime

Creating Your First Instance

Prerequisites

• At least one server connected to Supascale
• Server with minimum 2GB RAM and 2 CPU cores
• Docker and Docker Compose installed on target server
• Sufficient disk space (minimum 10GB recommended)

Deployment Process

1. Navigate to Instances

   • Go to Dashboard → Instances
   • Click "Create Instance"

2. Choose Target Server

   • Select from your connected servers
   • View server resources and current usage
   • Supascale recommends optimal servers based on available resources

3. Configure Instance Details

   Project Name:

   Format: lowercase-with-hyphens
   Examples: 
   - production-api
   - staging-app
   - client-website
   

   Project ID: Automatically generated unique identifier

   • Used for internal routing and identification
   • Cannot be changed after creation
   • Format: proj_abc123def456

   Environment: Choose deployment environment

   • Production: Optimized for performance and reliability
   • Staging: Balanced configuration for testing
   • Development: Resource-efficient for local development

4. Advanced Configuration (Optional)

   Resource Limits:

   resources:
     memory: "2G"        # RAM allocation
     cpu: "1.0"          # CPU cores
     disk: "20G"         # Storage limit
   

   Network Settings:

   network:
     external_access: true    # Allow external connections
     custom_domain: ""        # Optional custom domain
     ssl_enabled: true        # Enable HTTPS
   

   Database Configuration:

   database:
     max_connections: 100
     shared_preload_libraries: ["pg_stat_statements"]
     timezone: "UTC"
   

5. Deploy Instance

   • Click "Deploy Instance"
   • Monitor deployment progress in real-time
   • Typical deployment time: 2-5 minutes

Deployment Process Details

Phase 1: Preparation

• Validates server resources
• Allocates unique ports
• Generates secure credentials
• Creates project directory structure

Phase 2: Download

• Clones latest Supabase repository
• Downloads required Docker images
• Prepares configuration files

Phase 3: Configuration

• Generates JWT secrets and API keys
• Creates secure database passwords
• Configures environment variables
• Sets up network routing

Phase 4: Startup

• Starts Docker containers in correct order
• Waits for services to become healthy
• Verifies all connections are working
• Registers instance with monitoring

Instance Configuration

Automatic Configuration

Supascale automatically configures several critical settings:

Port Allocation:

• Each instance gets a unique port range (10 ports)
• Base port calculated automatically (e.g., 54000, 54010, 54020)
• Services mapped to specific port offsets:

  API Gateway:    Base + 0   (54000)
  Database:       Base + 1   (54001)
  Auth:           Base + 2   (54002)
  Storage:        Base + 3   (54003)
  Realtime:       Base + 4   (54004)
  Dashboard:      Base + 5   (54005)
  Inbucket:       Base + 6   (54006)
  

Security Credentials:

• Database Password: 32-character secure random string
• JWT Secret: Cryptographically secure secret for token signing
• API Keys:
  • anon key for public access
  • service_role key for administrative access
• Studio Password: Secure access to Supabase Studio

Environment Variables: All necessary environment variables are generated automatically:

POSTGRES_PASSWORD=<secure-password>
JWT_SECRET=<jwt-secret>
ANON_KEY=<anon-key>
SERVICE_ROLE_KEY=<service-key>
SITE_URL=https://your-domain.com

Custom Configuration

Environment-Specific Settings:

# Production configuration
production:
  database:
    max_connections: 200
    work_mem: "256MB"
    shared_buffers: "512MB"
  
  auth:
    jwt_expiry: 3600
    refresh_token_rotation: true
  
  storage:
    max_file_size: "50MB"
    allowed_mime_types: ["image/*", "video/*", "audio/*"]

# Development configuration  
development:
  database:
    max_connections: 50
    log_statement: "all"
  
  auth:
    jwt_expiry: 86400
    enable_signup: true
  
  cors:
    allowed_origins: ["http://localhost:3000", "http://localhost:8080"]

Custom Domains: Configure custom domains for professional deployment:

1. Add Domain in Dashboard

   • Go to Instance → Settings → Domains
   • Enter your domain name
   • Choose SSL certificate option

2. DNS Configuration

   • Point your domain to server IP address
   • Add CNAME record for subdomains if needed

3. SSL Certificate

   • Automatic Let's Encrypt certificates
   • Custom certificate upload supported
   • Wildcard certificates for subdomains

Instance Management

Lifecycle Operations

Start Instance:

• Brings up all Docker containers
• Waits for health checks to pass
• Updates status to "Running"
• Triggers monitoring alerts

Stop Instance:

• Gracefully shuts down containers
• Preserves all data and configurations
• Updates status to "Stopped"
• Maintains port reservations

Restart Instance:

• Performs stop followed by start
• Useful for applying configuration changes
• Zero data loss during restart
• Automatic health verification

Terminate Instance:

• Permanently deletes instance
• Option to preserve or delete data
• Releases allocated ports
• Cannot be undone

Instance Status States

Creating: Initial deployment in progress

• Downloading dependencies
• Configuring services
• Starting containers

Running: Instance is operational

• All services healthy
• Accepting connections
• Monitoring active

Stopped: Instance intentionally stopped

• Containers not running
• Data preserved
• Quick restart available

Error: Instance experiencing issues

• One or more services failed
• Automatic recovery attempted
• Manual intervention may be required

Updating: Instance being updated

• New version deployment
• Configuration changes
• Brief service interruption

Terminating: Instance being deleted

• Data cleanup in progress
• Port release
• Final status updates

Health Monitoring

Service Health Checks: Supascale continuously monitors each service:

health_checks:
  database:
    command: "pg_isready -U postgres"
    interval: 30s
    timeout: 10s
    retries: 3
  
  api:
    http:
      url: "http://localhost:3000/health"
      expected_status: 200
    interval: 30s
  
  auth:
    http:
      url: "http://localhost:9999/health"
    interval: 60s

Performance Metrics:

• Response time monitoring
• Database connection count
• Memory usage per service
• Disk I/O patterns
• Error rates and logs

Advanced Deployment Options

Multi-Instance Deployments

Deploy related instances across multiple servers:

Horizontal Scaling:

deployment:
  type: "horizontal"
  instances:
    - server: "web-01"
      role: "primary"
    - server: "web-02" 
      role: "replica"
  
  load_balancer:
    enabled: true
    algorithm: "round_robin"

Environment Separation:

environments:
  production:
    servers: ["prod-01", "prod-02"]
    resources:
      memory: "4G"
      cpu: "2.0"
  
  staging:
    servers: ["staging-01"]
    resources:
      memory: "2G"
      cpu: "1.0"

Blue-Green Deployments

Zero-downtime deployments using blue-green strategy:

1. Deploy to Green Environment

   • Create identical instance on different ports
   • Migrate data if necessary
   • Test functionality thoroughly

2. Switch Traffic

   • Update load balancer configuration
   • Gradually shift traffic to green
   • Monitor for issues

3. Cleanup Blue Environment

   • Keep blue running for rollback
   • After validation, terminate blue
   • Green becomes new blue for next deployment

Custom Docker Configurations

Custom Images:

services:
  database:
    image: "custom-postgres:14"
    build:
      context: "./custom-postgres"
      dockerfile: "Dockerfile"
  
  api:
    image: "postgrest/postgrest:v10.1.0"
    environment:
      PGRST_DB_EXTRA_SEARCH_PATH: "public,extensions"

Volume Mounts:

volumes:
  postgres_data:
    driver: "local"
    driver_opts:
      type: "none"
      o: "bind"
      device: "/mnt/ssd/postgres"
  
  storage_data:
    external: true
    name: "nfs_storage"

Security Configuration

Network Security

Firewall Rules: Supascale automatically configures firewall rules:

# Allow instance access
ufw allow 54000:54010/tcp

# Restrict dashboard access to specific IPs
ufw allow from 203.0.113.0/24 to any port 54005

# Block direct database access
ufw deny 54001/tcp

SSL/TLS Configuration:

• Automatic Let's Encrypt certificates
• TLS 1.3 support
• HSTS headers enabled
• Secure cipher suites only

Access Control

Database Security:

-- Automatic security configurations
ALTER SYSTEM SET ssl = 'on';
ALTER SYSTEM SET log_connections = 'on';
ALTER SYSTEM SET log_disconnections = 'on';

-- Row Level Security enabled by default
ALTER TABLE auth.users ENABLE ROW LEVEL SECURITY;

API Security:

• JWT validation on all endpoints
• Rate limiting per IP and user
• CORS configuration
• Input validation and sanitization

Troubleshooting

Common Deployment Issues

Insufficient Resources:

Error: Cannot allocate 2GB memory, only 1.2GB available
Solution: Choose server with more resources or reduce instance requirements

Port Conflicts:

Error: Port 54000 already in use
Solution: Supascale automatically resolves by finding next available port range

Docker Issues:

Error: Docker daemon not responding
Solution: Check Docker service status on target server

Performance Issues

Slow Startup:

• Check server resources during deployment
• Verify internet connectivity for image downloads
• Monitor disk I/O during container startup

Service Timeouts:

• Increase health check timeouts
• Check service logs for startup errors
• Verify network connectivity between services

Debugging Tools

Instance Logs:

# View all instance logs
supascale-agent logs --instance "project-name"

# Follow specific service logs
supascale-agent logs --instance "project-name" --service "database" --follow

# Export logs for analysis
supascale-agent logs --instance "project-name" --export "/tmp/logs.tar.gz"

Resource Monitoring:

# Check instance resource usage
docker stats

# Monitor specific container
docker stats container_name

# View detailed metrics
docker exec container_name top

Next: Learn about Instance Management for ongoing operations and maintenance.