SupaControl

Built With

SupaControl is a self-hosted management platform for orchestrating multi-tenant Supabase instances on Kubernetes. It provides a robust API and web dashboard for automated provisioning, monitoring, and lifecycle management of Supabase deployments.

Perfect for:

🏢 SaaS Providers offering Supabase as a managed service
👨‍💻 Development Teams managing multiple environments
🎓 Educational Institutions providing isolated instances for students
🏗️ Platform Engineers building internal developer platforms

Overview

SupaControl acts as a control plane that sits between you and your Kubernetes cluster, simplifying the complexity of managing multiple Supabase instances.

What It Does

🚀 Automates Supabase instance deployment using Helm charts
🔒 Isolates each instance in its own Kubernetes namespace
📊 Manages complete instance lifecycle (create, monitor, delete)
🔐 Secures API access with JWT authentication and API keys
🌐 Provides a modern web dashboard for visual management
🛠️ Integrates with CI/CD pipelines via REST API

Why SupaControl?

Without SupaControl:

# Manual Supabase deployment
helm repo add supabase https://...
kubectl create namespace supa-myapp
helm install myapp supabase/supabase -n supa-myapp -f custom-values.yaml
kubectl apply -f ingress.yaml -n supa-myapp
# Repeat for each instance... 😓

With SupaControl:

# One command deployment
supactl create myapp

# Or via API
curl -X POST https://supacontrol.example.com/api/v1/instances \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"name": "myapp"}'

Features

Core Features

🚀 Automated Provisioning: Deploy complete Supabase stacks with a single API call
🔒 Complete Isolation: Each instance in its own dedicated Kubernetes namespace
🔐 Security First: API key and JWT authentication, encrypted secrets management
📊 Persistent Inventory: PostgreSQL for users and API keys only; instance state managed via Kubernetes CRDs. See ADR 001 for details.
⏳ Asynchronous Operations: Instance creation and deletion are asynchronous; poll GET /api/v1/instances/:name for status updates.
🌐 Web Dashboard: Modern React-based UI for instance management
🔑 API Key Management: Generate, list, and revoke keys for CLI/programmatic access
🎯 Status Monitoring: Real-time instance health and deployment status
🗑️ Clean Deletion: Automated cleanup of namespaces and resources

Technical Highlights

API-First Design: Complete functionality exposed via REST API
Kubernetes-Native: Built on client-go and Helm v3 SDK
Stateless Application: Horizontally scalable for high availability
Declarative Orchestration: Kubernetes resources managed declaratively
Multi-Tenant Ready: Designed for managing dozens to hundreds of instances
Production-Ready: Includes health checks, logging, and error handling
CI/CD Friendly: Integrate with automated deployment pipelines

Use Cases

SaaS Multi-Tenancy

Customer A → Instance: supa-customer-a (dedicated database, isolated)
Customer B → Instance: supa-customer-b (dedicated database, isolated)
Customer C → Instance: supa-customer-c (dedicated database, isolated)

Development Environments

Production  → Instance: supa-prod
Staging     → Instance: supa-staging
Development → Instance: supa-dev
Testing     → Instance: supa-test

Educational Institutions

Student 1 → Instance: supa-student1 (isolated learning environment)
Student 2 → Instance: supa-student2 (isolated learning environment)
...

Architecture

High-Level Overview

┌─────────────────────────────────────────────────────────┐
│                      SupaControl                         │
│                   (Control Plane)                        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌──────────────┐    ┌──────────────┐                  │
│  │  Web UI      │    │  REST API    │                  │
│  │  (React)     │◄───┤  (Echo/Go)   │◄─── API Clients │
│  └──────────────┘    └──────┬───────┘                  │
│                              │                           │
│                    ┌─────────▼──────────┐               │
│                    │   Orchestrator     │               │
│                    │   (K8s + Helm)     │               │
│                    └─────────┬──────────┘               │
│                              │                           │
│                    ┌─────────▼──────────┐               │
│                    │  Inventory DB      │               │
│                    │  (PostgreSQL)      │               │
│                    └────────────────────┘               │
└─────────────────────────────────────────────────────────┘
                               │
                      ┌─────────▼──────────┐
                      │  Kubernetes API    │
                      └─────────┬──────────┘
                                │
          ┌─────────────────────┼─────────────────────┐
          │                     │                     │
     ┌────▼────┐           ┌────▼────┐           ┌────▼────┐
     │Instance1│           │Instance2│           │Instance3│
     │Namespace│           │Namespace│           │Namespace│
     │supa-app1│           │supa-app2│           │supa-app3│
     │         │           │         │           │         │
     │ Supabase│           │ Supabase│           │ Supabase│
     │  Stack  │           │  Stack  │           │  Stack  │
     └─────────┘           └─────────┘           └─────────┘

For detailed architecture documentation, see ARCHITECTURE.md.

Instance State Management

SupaControl uses Kubernetes Custom Resource Definitions (CRDs) as the single source of truth for instance state. The SupabaseInstance CRD tracks the desired and actual state of each Supabase deployment, enabling declarative management and reconciliation.

┌─────────────────┐
│   SupabaseInstance CRD   │
│     (Desired State)      │
└─────────┬───────────────┘
          │ Watches
┌─────────▼──────────┐
│   Controller       │
│   (Reconciles)     │
└─────────┬──────────┘
          │ Creates/Manages
          ▼
┌──────────────────┐
│  Supabase Stack  │
│ (Actual State)   │
└──────────────────┘

See ADR 001 for the rationale behind using CRDs.

Quick Start

The fastest way to get started with SupaControl is using our interactive installer.

Note: Currently requires git clone as no npx installer is available.

Prerequisites Checklist

Before you begin, ensure you have:

✅ Kubernetes Cluster (v1.24+) running and accessible
✅ kubectl installed and configured
✅ Helm (v3.13+) installed
✅ Ingress Controller (e.g., nginx-ingress) deployed in your cluster
⚠️ DNS/Domain configured for accessing the dashboard

Quick Prerequisites Check:

# Verify kubectl
kubectl version --client

# Verify Helm
helm version

# Verify cluster access
kubectl cluster-info

# Verify ingress controller
kubectl get ingressclass

5-Minute Install

# 1. Clone the repository
git clone https://github.com/qubitquilt/SupaControl.git
cd SupaControl/cli

# 2. Install dependencies
npm install

# 3. Run interactive installer
npm start

The installer will:

✅ Check all prerequisites
🔐 Generate secure secrets automatically
📝 Guide you through configuration (domain, ingress, etc.)
🚀 Deploy to your Kubernetes cluster
📋 Provide access information and next steps

After installation completes:

# 1. Wait for pods to be ready (1-2 minutes)
kubectl get pods -n supacontrol --watch

# 2. Access the dashboard
# Navigate to https://supacontrol.yourdomain.com

# 3. Login with default credentials
# Username: admin
# Password: admin
# ⚠️ CHANGE THIS IMMEDIATELY!

First Steps After Install

# 1. Access dashboard and change default password
# Go to Settings → Change Password

# 2. Generate an API key for CLI access
# Go to Settings → API Keys → Create New Key

# 3. Install the CLI tool
curl -sSL https://raw.githubusercontent.com/qubitquilt/supactl/main/scripts/install.sh | bash

# 4. Login to SupaControl
supactl login https://supacontrol.yourdomain.com

# 5. Create your first Supabase instance
supactl create my-first-app

# 6. Check instance status
supactl status my-first-app

# 7. List all instances
supactl list

Installation

Option 1: Interactive Installer (Recommended)

The easiest way to install SupaControl. See Quick Start above.

Full CLI installer documentation: cli/README.md

Option 2: Manual Helm Installation

For advanced users who want full control over the installation.

# 1. Clone repository
git clone https://github.com/qubitquilt/SupaControl.git
cd SupaControl

# 2. Create values.yaml
cat > values.yaml <<EOF
config:
  jwtSecret: "your-very-long-and-secure-jwt-secret-here-change-this"
  database:
    host: "supacontrol-postgresql"
    port: "5432"
    user: "supacontrol"
    password: "your-secure-db-password-here-change-this"
    name: "supacontrol"
  kubernetes:
    ingressClass: "nginx"
    ingressDomain: "supabase.yourdomain.com"

ingress:
  enabled: true
  className: "nginx"
  hosts:
    - host: supacontrol.yourdomain.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: supacontrol-tls
      hosts:
        - supacontrol.yourdomain.com

postgresql:
  enabled: true
  auth:
    password: "your-secure-postgres-password-here"
    database: "supacontrol"
    username: "supacontrol"
EOF

# 3. Install with Helm
kubectl create namespace supacontrol
helm install supacontrol ./charts/supacontrol \
  -f values.yaml \
  -n supacontrol

# 4. Watch deployment
kubectl get pods -n supacontrol --watch

Option 3: Development Mode

For local development without Kubernetes:

Before running, ensure KUBECONFIG is set for local Kubernetes development. See docs/DEVELOPMENT.md for detailed setup instructions and troubleshooting.

# 1. Start PostgreSQL
docker run --name supacontrol-postgres \
  -e POSTGRES_USER=supacontrol \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=supacontrol \
  -p 5432:5432 \
  -d postgres:14

# 2. Set environment variables
export DB_HOST=localhost DB_PORT=5432
export DB_USER=supacontrol DB_PASSWORD=password DB_NAME=supacontrol
export JWT_SECRET=your-dev-jwt-secret-at-least-32-chars

# 3. Run backend
cd server && go run main.go

# 4. Run frontend (in another terminal)
cd ui && npm install && npm run dev

Usage

Web Dashboard

Access the dashboard at https://supacontrol.yourdomain.com

Dashboard Features:

📊 Instance Overview - List all Supabase instances with status
➕ Create Instances - Deploy new instances with one click
🗑️ Delete Instances - Remove instances and clean up resources
🔑 API Key Management - Generate and revoke API keys
👤 User Settings - Change password and manage account

API Usage

All API endpoints require authentication except /healthz and /api/v1/auth/login.

Quick Example:

# 1. Login
TOKEN=$(curl -X POST https://supacontrol.example.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}' | jq -r '.token')

# 2. Create instance
curl -X POST https://supacontrol.example.com/api/v1/instances \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-app"}'

# Note: Instance creation is asynchronous. Poll for status:
curl -X GET https://supacontrol.example.com/api/v1/instances/my-app \
  -H "Authorization: Bearer $TOKEN"

# 3. List instances
curl -X GET https://supacontrol.example.com/api/v1/instances \
  -H "Authorization: Bearer $TOKEN"

Complete API documentation: docs/API.md

Configuration

Environment Variables

Variable	Description	Default	Required
`SERVER_PORT`	HTTP server port	`8091`	No
`DB_HOST`	PostgreSQL host	`localhost`	Yes
`DB_PORT`	PostgreSQL port	`5432`	Yes
`DB_USER`	Database username	`supacontrol`	Yes
`DB_PASSWORD`	Database password	-	Yes
`DB_NAME`	Database name	`supacontrol`	Yes
`JWT_SECRET`	JWT signing secret	-	Yes
`KUBECONFIG`	Path to kubeconfig	Empty (in-cluster)	No
`DEFAULT_INGRESS_CLASS`	Ingress class	`nginx`	No
`DEFAULT_INGRESS_DOMAIN`	Base domain for instances	`supabase.example.com`	No

Note for Developers: The KUBECONFIG environment variable is crucial for local Kubernetes development. See the Development Guide for detailed setup instructions and troubleshooting.

For complete configuration options, see the Helm chart values.

Documentation

Comprehensive documentation is available in the /docs directory:

Getting Started

📘 README.md (this file) - Overview and quick start
🚀 cli/README.md - CLI installer documentation

Technical Documentation

🏗️ ARCHITECTURE.md - System design and architecture
📡 docs/API.md - Complete API reference
🚀 docs/DEPLOYMENT.md - Production deployment guide
💻 docs/DEVELOPMENT.md - Development setup and guidelines
🔒 docs/SECURITY.md - Security best practices
🔧 docs/TROUBLESHOOTING.md - Common issues and solutions

Contributing

🤝 CONTRIBUTING.md - Contribution guidelines
🧪 TESTING.md - Testing documentation
🤖 CLAUDE.md - AI assistant development guide

CLI Tool

The project's cli/ directory contains the interactive installer for SupaControl. For the full supactl CLI tool, see https://github.com/qubitquilt/supactl. Features like local mode are available in the external repository.

Installation

# Linux/macOS
curl -sSL https://raw.githubusercontent.com/qubitquilt/supactl/main/scripts/install.sh | bash

# Or download from releases
# https://github.com/qubitquilt/supactl/releases

Quick Start

# Login to SupaControl server
supactl login https://supacontrol.yourdomain.com

# Create instance
supactl create my-project

# List instances
supactl list

# Check instance status
supactl status my-project

# Delete instance
supactl delete my-project

Features

🚀 Single binary - No dependencies, works everywhere
🔐 Secure auth - Credential management built-in
📂 Directory linking - Associate local dirs with instances
🎨 Interactive UI - Beautiful prompts and progress indicators
🐳 Local mode - Manage Docker-based instances without a server

Full CLI documentation: github.com/qubitquilt/supactl

Roadmap

Planned Features

v0.2.0

Instance update/upgrade support
Custom resource limits per instance
Instance status webhooks
Backup and restore functionality

v0.3.0

Prometheus metrics integration
Grafana dashboards
Instance templates/presets
Multi-cluster support

v0.4.0

Cost tracking per instance
Resource quota management
Advanced RBAC (user roles)
Audit logging

Future

Contributing to Roadmap

Have ideas? We'd love to hear them!

💡 Open a feature request
🗳️ Vote on existing feature requests
💬 Join discussions on GitHub

Contributing

We welcome contributions! Whether you're fixing bugs, improving documentation, or proposing new features, we appreciate your help.

Quick Start

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Test: make test
Commit: git commit -m 'feat: add amazing feature'
Push: git push origin feature/amazing-feature
Open a Pull Request

Ways to Contribute

🧪 Testing - Improve test coverage (currently ~6%). See TESTING.md for details.
📝 Documentation - Tutorials, guides, examples
🐛 Bug Fixes - Fix reported issues
✨ Features - Implement roadmap items
🎨 UI/UX - Improve dashboard design
🔒 Security - Security audits and improvements

See CONTRIBUTING.md for detailed guidelines.

License

MIT License - See LICENSE.md for details.

Support

Documentation

README (this file) - Overview and getting started
Complete Documentation - All technical documentation
CONTRIBUTING.md - Contribution guidelines
TESTING.md - Testing documentation

Community

💬 Discussions - GitHub Discussions
🐛 Bug Reports - GitHub Issues
💡 Feature Requests - GitHub Issues

Related Projects

supactl - Official CLI tool for SupaControl
supabase-kubernetes - Community Helm chart for Supabase

Acknowledgments

SupaControl is built on excellent open-source projects:

Supabase - The open source Firebase alternative
supabase-kubernetes - Community Helm chart
Kubernetes - Container orchestration platform
Helm - The package manager for Kubernetes
Echo - High performance Go web framework
React - JavaScript library for user interfaces
Vite - Next generation frontend tooling
client-go - Go client for Kubernetes
sqlx - Extensions to Go's database/sql

Special thanks to all contributors!

SupaControl - Self-hosted Supabase management, simplified.

Get Started · Documentation · Report Bug · Request Feature

Made with ❤️ by the SupaControl community

Name		Name	Last commit message	Last commit date
Latest commit History 203 Commits
.github		.github
charts/supacontrol		charts/supacontrol
cli		cli
deploy		deploy
docs		docs
pkg/api-types		pkg/api-types
scripts		scripts
server		server
ui		ui
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
ARCHITECTURE.md		ARCHITECTURE.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE.md		LICENSE.md
Makefile		Makefile
README.md		README.md
SUPACTL_ALIGNMENT_RECOMMENDATIONS.md		SUPACTL_ALIGNMENT_RECOMMENDATIONS.md
TESTING.md		TESTING.md
TESTING_IMPROVEMENTS.md		TESTING_IMPROVEMENTS.md
codecov.yml		codecov.yml

License

qubitquilt/SupaControl

Folders and files

Latest commit

History

Repository files navigation

SupaControl

Built With

Table of Contents

Overview

What It Does

Why SupaControl?

Features

Core Features

Technical Highlights

Use Cases

Architecture

High-Level Overview

Instance State Management

Quick Start

Prerequisites Checklist

5-Minute Install

First Steps After Install

Installation

Option 1: Interactive Installer (Recommended)

Option 2: Manual Helm Installation

Option 3: Development Mode

Usage

Web Dashboard

API Usage

Configuration

Environment Variables

Documentation

Getting Started

Technical Documentation

Contributing

CLI Tool

Installation

Quick Start

Features

Roadmap

Planned Features

v0.2.0

v0.3.0

v0.4.0

Future

Contributing to Roadmap

Contributing

Quick Start

Ways to Contribute

License

Support

Documentation

Community

Related Projects

Acknowledgments

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages