Migrate from Instant Cloud

Migrating from Instant Cloud happens in two phases:

Rehearse the migration: Set up self-hosted Instant and restore a test backup. This confirms that everything works and gives you an estimate for downtime.
Cut over: Pause writes, restore a fresh backup, and point your app at your self-hosted Instant.

#Rehearse the migration

#Set up self-hosted Instant

If you haven't already, set up self-hosting with our VPS or AWS guide. Make sure you can log in to the dashboard, create an app, query it, and write data.

Before restoring your app:

Configure Postmark so magic code emails work.
Restrict dashboard signups and disable temporary apps to prevent unwanted app creation.
Configure webhooks for your self-hosted app if your app uses them.

If your app uses OAuth for end-user sign-in, recreate each OAuth provider on the restored app. Copy its client ID, client secret, and any other provider settings. Then add the self-hosted callback URL to the provider:

https://api.myinstant.com/runtime/oauth/callback

Keep the Instant Cloud callback configured until the migration is complete.

#Restore a test backup

Migrating without data loss will require some downtime. To get a sense of how much time it will take, we'll do the following:

Export a backup from Instant Cloud
Restore the backup into your self-hosted Instant.

After restoring, verify that the following look correct:

Schema and permissions
Application data
Files
Magic code and each OAuth provider your app uses
Email templates

#Prepare the client change

After successfully restoring the test backup, we can put up a PR to update our clients to point to our new self-hosted Instant app.

Choose a new app ID for the self-hosted app. The ID must be a valid UUID. You can generate one in the terminal with:

uuidgen

This will be your app ID going forward.

Create a PR that points your app at self-hosted Instant, but do not merge it yet. Update the app ID, API URL, and WebSocket URL in every client init call:

const db = init({
  appId: 'YOUR_NEW_APP_ID',
  apiURI: 'https://api.myinstant.com',
  websocketURI: 'wss://api.myinstant.com/runtime/session',
});

If you use the Admin SDK, update its app ID, admin token, and apiURI too. Keep the PR ready to merge as soon as the final restore finishes.

#Cut over

#Pause writes on Instant Cloud

Open the app's Admin page in the Instant Cloud dashboard. Turn on Read-only mode, then wait 30 seconds for in-flight mutations to finish.

Reads, live queries, and presence will keep working. New writes will be rejected, including offline writes queued on user devices. We do this to ensure there is no data loss during the cutover.

#Restore the final backup

Create an on-demand backup of the Instant Cloud app and restore it into self-hosted Instant using the app ID from the rehearsal.

Before merging our earlier PR to switch clients over:

Check that /health/system returns {"wal":"ok"}.
Check the restored schema, permissions, data, and files.
Make sure Read-only mode is off on the self-hosted app.
Test magic code and OAuth login if your app uses them.

#Switch to self-hosted Instant

Merge and deploy the PR you prepared earlier. New client connections will now use the restored app on self-hosted Instant. Users may need to sign in again.

Watch the deployment and verify queries, writes, authentication, and file uploads. Once clients begin writing to self-hosted Instant, the Instant Cloud copy is no longer current. If you use OAuth, you can remove the Instant Cloud callback URL from each OAuth provider.

The migration should now be complete. Huzzah! 🎉

instant