Skip to main content

Migrate from Cloud to Self-hosted

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

This guide outlines the steps required to copy your apps and configuration from your Cloud to self-hosted deployment. Before you begin, review the pricing page to confirm your self-hosted 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.
  • A working self-hosted instance of Retool. To deploy a self-hosted instance of Retool, obtain a license key from your Retool account manager, or using our self-hosted Portal. Follow the deployment guides for additional instructions.
  • Admin permissions on both instances.
Caution

To use Retool Workflows or Retool Database, ensure that you configure your self-hosted deployment to support Retool Workflows and/or Retool Database.

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 the Enterprise plan. Reach out to your Retool account manager for more information.

1. Configure Source Control​

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

2. Migrate resources​

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

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

Self-hosted instances can use environment variables or secrets managers, such as AWS Secrets Manager and HashiCorp Vault, to store sensitive credentials. Consider storing credentials, such as database passwords and API keys, using one of these methods.

note

All plans support environment variables. The Enterprise plan supports integrations with secrets managers.

3. Retool Database​

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

4. Copy Query Library queries​

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

5. Migrate apps and workflows​

To migrate apps and workflows:

Caution

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

6. Test apps and workflows​

On your self-hosted instance, test the most critical apps and workflows.

Without Source Control​

If you don't use Source Control, use the following steps to copy your apps and workflows to your self-hosted instance.

1. Recreate resources​

Cloud resources may use config vars to set credentials, such as passwords or API keys. First, manually migrate config vars to the self-hosted instance.

Next, recreate all resources in your self-hosted instance. Ensure both instances use the same resource names. If your resource names differ, imported apps and workflows will not work properly.

Self-hosted instances can use environment variables, or secrets managers such as AWS Secrets Manager and HashiCorp Vault, to store sensitive credentials. Consider moving credentials such as database passwords, or API keys, to one of these methods.

note

All plans support environment variables. The Enterprise plan supports integrations with secrets managers.

2. Retool Database​

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

3. Copy Query Library queries​

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

4. Export apps and workflows​

Caution

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, and you create individual exports for each app and workflow. To export an app or workflow, click the ••• button to open the contextual menu, then select Export and download.

Now, import these into your self-hosted organization.

  • To import a classic app, create a new app. In the ••• menu, click Replace app with JSON/ZIP.
  • To import a workflow, click Import from the workflows landing page.

5. Test apps and workflows​

On your self-hosted instance, test the most critical apps and workflows.

Update your organization settings​

Update the self-hosted 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 Cloud instance to your self-hosted instance. You must manually recreate themes in your self-hosted instance. Check the Settings page for any other settings you need to migrate to the new instance, including Beta feature flags.

3. Usage Analytics​

To set up usage analytics on your self-hosted instance, reach out to your Retool account manager to obtain an access token. After you have a token, follow the instructions to enable usage analytics.

Downgrade plan​

When you no longer need to use your Cloud organization, downgrade it to the Free plan. Navigate to the Billing settings and click Downgrade. Ensure you have migrated all your apps, resources, workflows, and database tables before doing this.