Skip to main content

Migrate from Self-hosted to Cloud

Learn how to migrate from a Self-hosted deployment to Retool Cloud.

This guide outlines the steps required to copy your apps and configuration from your self-hosted deployment to Retool Cloud. Before you begin, review the pricing page to confirm your Cloud plan supports the features you need. Self-hosted plans have a different set of supported features and may have a different billing structure than Cloud plans.

Requirements​

To perform this migration, you need:

  • A working Cloud instance of Retool. To create Cloud instance of Retool, sign up for an account on retool.com.
  • A working Self-hosted instance of Retool.
  • Admin permissions on both instances.

Before migrating, upgrade your self-hosted instance to the most recent version of Retool. Self-hosted releases are typically two weeks behind Cloud releases, so your self-hosted instance may be missing features already on your Cloud instance. Typically this does not cause any issues, but you may need to make minor modifications to your applications on the self-hosted instance.

If your plan includes Source Control, follow the instructions for migrating with Source Control. Otherwise, follow the instructions for migrating without Source Control.

With Source Control​

If you use Source Control in Retool, use the following steps to synchronize apps, resources, and workflows between your Cloud and self-hosted instances. Source Control is available on Enterprise plans. Reach out to your Retool account manager if you are interested in an Enterprise plan.

1. Configure Source Control​

Ensure you have configured Source Control on your self-hosted instance and that you can access its repository. Next, set up source control on your Cloud instance. Use the same provider and repository as your self-hosted instance. Source Control with GitHub and GitLab are supported on Retool Cloud.

2. Migrate resources​

If your self-hosted instance uses config vars to set credentials, manually copy these config vars to your Cloud instance.

note

If you use environment variables, AWS Secrets Manager, or HashiCorp Vault to store credentials, you need to store those credentials as secret config vars, or directly within the resource configuration page.

Next, migrate your resources:

Confirm that you can see your resources in the self-hosted instance.

3. Retool Database​

To migrate Retool Database from your self-hosted instance to Cloud, manually export and import each table into the Cloud instance. You can export a CSV for each table on your self-hosted instance, and import each CSV into your Cloud database.

4. Copy Query Library queries​

Queries in the Query Library are not synchronized with Source Control. In your Cloud instance, manually recreate any shared queries used in your self-hosted instance.

5. Migrate apps and workflows​

To migrate apps and workflows:

warning

Workflow webhook URLs change during the migration, so make sure to update any webhooks which are referenced elsewhere in your stack.

7. Test apps and workflows​

On your Cloud instance, test the most critical apps and workflows.

Without Source Control​

If you don't use Source Control or your plan does not include Source Control, use the following steps to copy your apps and workflows to your Cloud instance. Business and Team plans do not include Source Control.

1. Recreate resources​

If your self-hosted instance uses config vars to set credentials, manually copy these config vars to your Cloud instance.

note

If you are using environment variables, AWS Secrets Manager, or HashiCorp Vault to store credentials, store those credentials as secret config vars or directly within the resource configuration page.

Next, recreate all resources in your Cloud instance. Ensure that resource names are identical between instances. If your resource names differ, imported apps and workflows will not work properly.

2. Retool Database​

To migrate Retool Database from your self-hosted instance to Cloud, manually export and import each table into the Cloud instance. You can export a CSV for each table on your self-hosted instance, and import each CSV.

3. Copy Query Library queries​

Queries in the Query Library are not synchronized with Source Control. In your Cloud instance, manually recreate any shared queries used in your self-hosted instance.

4. Export apps and workflows​

warning

Workflow webhook URLs change during the migration, so make sure to update any webhooks you reference elsewhere in your stack.

Next, export your apps and workflows as JSON. Exports include any queries and configuration options in use.

Apps and workflows are exported individually. To export an app, click the ••• button to open the contextual menu, then select Export and download.

Now, import these into your Cloud organization. To import an app or workflow, click Create new and select From JSON.

5. Perform application testing​

On your Cloud instance, test the most critical apps and workflows.

Update your organization​

Update the Cloud deployment to invite users and copy over settings.

1. Invite users​

After migrating apps and workflows, add your users to the new instance using single-sign on (SSO) or email and password authentication. Retool strongly recommends using SSO to authenticate users. SSO is more secure than email and password authentication, and using an identity provider can simplify the process of managing your users.

note

All plans support SSO with Google. The Enterprise plan supports SSO using any SAML or OIDC identity provider.

Provision users​

If you authenticate using SSO, and your identity provider supports JIT user provisioning, you can automatically migrate users by configuring SSO and JIT provisioning on the new instance. When a user signs in using SSO to the new instance, Retool automatically creates a new user account.

If you use email and password authentication, manually migrate users by sending email invitations. You can bulk invite users by inserting a comma-separated list of email addresses. When a user signs up using the link in the email invite, Retool creates a new user account.

Migrate permission groups​

You can migrate permission groups with role mapping or by manually recreating permission groups.

If you use role mapping with an OIDC or SAML-based identity provider, you can set up role mapping on the new instance to migrate groups. After configuring role mapping, your permission groups automatically migrate to the new instance.

If you do not use role mapping, recreate your permission groups in your new instance and add your users to them.

2. Copy settings​

Copy app themes, custom branding, and any org-wide JavaScript from your self-hosted instance to your Cloud instance. You must manually recreate themes in your Cloud instance. Check the Settings page for any other settings you need to migrate to the new instance, including Beta feature flags.

Downgrade plan​

When you no longer need to use the self-hosted organization, downgrade it to the Free plan. Navigate to Retool Self-hosted Portal and change your plan to a free plan.