Technical Questions

Technical frequently asked questions about Supascale architecture, configuration, and advanced usage.

Architecture

What technology stack does Supascale use?

Why SQLite instead of PostgreSQL?

Supascale uses SQLite for:

• Zero configuration - No separate database server
• Portability - Easy backup and migration
• Low resource usage - Suitable for small servers
• Reliability - Battle-tested, no network issues

SQLite handles Supascale's use case (configuration storage, not high-throughput) excellently.

How does Supascale manage Docker containers?

Supascale:

1. Generates docker-compose.yml for each project
2. Uses Docker Compose API to start/stop services
3. Monitors container health via Docker API
4. Collects logs via Docker logging driver

Can Supascale run without Docker?

No. Docker is required because Supabase services are distributed as Docker images. Supascale orchestrates these containers.

Performance

What are the minimum system requirements?

How many projects can one server handle?

Depends on resources:

Projects can be tuned to use fewer resources by disabling unused services.

How do I reduce memory usage?

1. Disable unused services:

   • Edge Functions (if not used)
   • Realtime (if not needed)
   • Vector (if not using pgvector)

2. Tune PostgreSQL:

   # In docker-compose.yml
   services:
     db:
       command: >
         postgres -c shared_buffers=128MB
                  -c work_mem=8MB
   

3. Enable connection pooling (PgBouncer)

Can I use Supascale on ARM processors?

Yes, with limitations:

• Supabase images support arm64 (Apple Silicon, AWS Graviton)
• Some services may have reduced performance
• Verify all required images support ARM

Security

How are sensitive data encrypted?

The DB_ENCRYPTION_KEY environment variable is used for all symmetric encryption.

How do I rotate the encryption key?

Key rotation requires decrypting and re-encrypting all sensitive data. Plan carefully.

1. Export all sensitive configuration
2. Update DB_ENCRYPTION_KEY
3. Re-import configuration
4. Verify all services work

What authentication methods are supported?

For Supascale admin access:

• Username/password (stored with bcrypt)
• Session-based authentication (NextAuth.js)
• API key authentication

For Supabase projects:

• All Supabase auth providers (configured per project)

How do I secure Supascale behind a firewall?

# Only allow local access
ufw allow from 192.168.1.0/24 to any port 3000

# Or use SSH tunnel
ssh -L 3000:localhost:3000 your-server

Are API communications encrypted?

• Web UI: Use HTTPS (reverse proxy with SSL)
• Docker API: Local socket (no network exposure)
• Database: Local SQLite (no network)

Database

Can I view/edit the Supascale database directly?

Yes:

sqlite3 data/supascale.db

# View tables
.tables

# View schema
.schema projects

Direct database edits can corrupt data. Always back up first.

How do I reset Supascale to fresh state?

# Stop Supascale
pm2 stop supascale-web

# Remove database (keeps projects)
rm data/supascale.db

# Restart (re-runs setup)
pm2 start supascale-web

Can I use an external database?

Not currently. SQLite is embedded. External database support (PostgreSQL) may be added in future versions.

Docker

How do I use a custom Docker registry?

Set environment variable:

DOCKER_REGISTRY=your-registry.com

Or modify image paths in project settings.

Can I customize the Docker Compose configuration?

Yes, but with caveats:

1. Changes may be overwritten on project updates
2. Use Supascale settings when possible
3. For advanced needs, edit files directly:

   vim ~/supabase/projects/your-project/docker-compose.yml
   docker compose up -d
   

How do I update Supabase Docker images?

1. Via UI: Project Settings > Services > Update
2. Via API: Use container update scheduled task
3. Manually:

   cd ~/supabase/projects/your-project
   docker compose pull
   docker compose up -d
   

Can I run Supascale in Docker?

Not officially supported yet. Challenges:

• Docker-in-Docker complexity
• Volume mount management
• Network configuration

Running directly on host is recommended.

Networking

What ports does Supascale use?

Can multiple projects share ports?

No. Each project needs unique ports. Supascale automatically assigns ports starting from 54321.

How do I configure projects for external access?

1. Use domain binding with Supascale
2. Configure reverse proxy (Nginx/Caddy)
3. Set up SSL via Let's Encrypt

Does Supascale support IPv6?

Yes, if your Docker and network support IPv6:

# In docker-compose.yml
networks:
  default:
    enable_ipv6: true

API

What's the API rate limit?

Default limits:

• 1000 requests per minute per API key
• Configurable via environment variables

Can I use the API without authentication?

No. All API endpoints require either:

• Valid session (web UI)
• API key header (X-API-Key)

How do I debug API issues?

1. Check response body for error details
2. Enable debug logging:

   DEBUG=supascale:* pm2 restart supascale-web
   

3. Check Supascale logs:

   pm2 logs supascale-web
   

Backups

What backup formats are used?

Can I restore to a different project?

Partial support:

• Database: Yes (schema may need adjustment)
• Storage: Yes
• Functions: Yes
• Config: Not directly (project-specific)

How do I automate off-site backups?

1. Configure cloud storage provider
2. Create scheduled backup task
3. Set destination to cloud storage
4. Enable encryption for sensitive data

Updates

How do I roll back an update?

1. Stop Supascale
2. Restore from git:

   git checkout v1.0.0  # Previous version tag
   npm install
   npm run build
   

3. Restart Supascale

Do updates require downtime?

Minimal downtime:

1. New version downloads in background
2. Brief restart required (~30 seconds)
3. Projects continue running

Can I skip versions when updating?

Yes. Update directly to latest. Database migrations handle version gaps.

Troubleshooting

Where are log files?

How do I enable verbose logging?

# Set debug environment
DEBUG=* pm2 restart supascale-web

# For specific modules
DEBUG=supascale:api:* pm2 restart supascale-web

How do I report a technical issue?

Include:

1. Supascale version (/api/v1/system/updates)
2. Operating system and version
3. Docker version (docker --version)
4. Error logs (pm2 logs supascale-web --lines 100)
5. Steps to reproduce