Cloud to Self-Hosted Migration

Moving from Supabase Cloud to a self-hosted instance gives you full control over your infrastructure, predictable costs, and the ability to customize your stack. Stack2X handles the heavy lifting, but there are a few things you need to prepare before starting.

Prerequisites

Before you open the migration wizard, make sure these are in place:

Your self-hosted instance is running and stable. Whether you are using Docker Compose, Kubernetes, or a managed hosting provider, your Supabase instance should be fully deployed. The dashboard should load, the API should respond, and the database should be accepting connections.

DNS and SSL are configured. Your self-hosted instance needs a domain or subdomain pointed at it, with active SSL certificates. This is how your application will connect after migration.

Both instances are added to Stack2X. Go to the Instances page and add your Cloud project (with at least Full Backup permission) and your self-hosted instance (with Full Access permission). Test both connections to confirm they are working.

You have a recent backup. Before any migration, create a backup of your Cloud project through Stack2X or through the Supabase dashboard. This is your safety net.

Connecting Both Instances

Your Cloud project connects through a database connection string and, for cloud-only components, through Supabase OAuth. When you add a Cloud instance, Stack2X prompts you to authorize via OAuth to access the Management API. This is required for components like edge functions, auth configuration, and secrets.

Your self-hosted instance connects through a direct database connection string. Since there is no Management API for self-hosted, cloud-only components will not be available as targets.

Component Considerations

When migrating from Cloud to self-hosted, keep these points in mind:

Cloud-only components will be skipped. Components like Edge Functions, Secrets, Auth Configuration, Email Templates, PostgREST Config, Network Restrictions, SSL Enforcement, Storage Config, Realtime Config, and Custom Domains rely on the Supabase Management API. Since your target is self-hosted, the wizard flags these and skips them during execution. You will need to configure these manually on your self-hosted instance.

Core components work normally. Database Schema, Database Data, RLS Policies, Auth Users, Storage Buckets and Objects, Realtime Configuration, and Integrations all migrate directly through the database connection and Supabase API. These are the foundation of your project.

Auth users will need to re-authenticate. Because the JWT secret on your self-hosted instance differs from Cloud, all existing user sessions become invalid. Users will need to log in again. Plan for this in your communication to users.

Storage files transfer through the API. Bucket configurations and individual objects are downloaded from Cloud and uploaded to your self-hosted storage. For large storage volumes, this step takes the longest. Make sure your server has enough disk space.

Running the Migration

Open the migration wizard and follow the five steps:

1. Select your Cloud project as the source.
2. Select your self-hosted instance as the target.
3. Choose your components. Start with the essentials: Database Schema, Database Data, RLS Policies, Auth Users, and Storage Buckets. The wizard shows cloud-only components with a badge and warns you on the review screen that they will be skipped.
4. Review the summary, resolve any OAuth warnings for the source, check the confirmation box, and click Start Migration.
5. Monitor progress as each component processes.

Before starting, put your application in maintenance mode or freeze writes to the Cloud project. This prevents new data from being created on the source while the migration is running.

Post-Migration Steps

Update your application configuration. Point your app's Supabase client URL and API keys to the self-hosted instance. Deploy this change.

Configure cloud-only features manually. Set up auth providers, SMTP settings, email templates, and edge functions directly on your self-hosted instance. These did not migrate automatically.

Update DNS records. If you use a custom domain, point it at your self-hosted instance. Allow time for DNS propagation.

Verify everything. Check that users can log in, data is present, storage files load, and your application works end-to-end against the new instance.

Keep Cloud running temporarily. Do not delete your Cloud project yet. Keep it available as a fallback for at least two weeks while you confirm stability on the self-hosted side.