This guide describes the recommended steps to upgrade the Retool software installed on your on-premise Retool deployment.
- Choose the version of Retool to upgrade to. Understand the changes between your current Retool version and the new version.
- [Recommended] Pick a set of your Retool apps to use to test the new version of Retool.
- Schedule downtime for the upgrade.
- [If needed] Spin up a separate, temporary Retool instance and seed it with your current apps.
- Install the new version of Retool.
- Test your apps on the new version of Retool.
- Remind your users about the start of the scheduled downtime.
- Take a full backup of your Retool instance(s), and then install the new version of Retool.
- Let your users know when the upgrade is complete.
Below, we cover each of these steps in detail.
1. Choose the version of Retool to upgrade to. Understand the changes between your current Retool version and the new version.
Check the Releases page to see each version of Retool and its changelog. Read the changelogs between your current version of Retool and the version of Retool you are upgrading to, to understand all the changes in between.
- If any feature is being deprecated in a version of Retool, the changelog will contain instructions for how to adapt to the change.
In most cases, you will want to upgrade to the most recent version of Retool. However, in the rare case where we have deprecated a feature in the newest version of Retool, you may upgrade to a version before that deprecation, and then take time to migrate off that feature before adopting the newest version.
Here are some suggestions for how to pick the apps.
- If possible, include your most mission-critical apps in this set.
- Select apps that use a variety of backend Resources and frontend Components.
- Select at least 3 apps.
As a precaution, we recommend scheduling downtime, even if it’s 10-15 minutes, during off-peak hours to do the upgrade. (Note: If you are running Retool as a single container/node, you will naturally experience brief downtime during the upgrade.) During this time, users should not be using or editing Retool apps. Make an announcement to your users at least a few days in advance.
If you run multiple Retool instances—for example, dev, staging, and production instances—you may consider scheduling separate downtime for each: for example, upgrading dev first, and then staging, and then production.
The amount of time to schedule may vary depending on various factors (for example, whether you have point-in-time recovery enabled on your database, or need time to take a database snapshot). If this is your first time running an upgrade, you can use the next step (“Test on a sandbox instance”) to help establish a baseline.
By running your upgrade on a sandbox instance, you can test out the upgrade process in a low-stakes environment and build confidence for the upgrades in your main Retool instance(s). As you go through the steps below, you may find it helpful to write an internal upgrade runbook (or update an existing runbook, if you have one), that you can follow for your main Retool instance(s). Your runbook can include specific context and commands for your company and become a resource for other colleagues.
Testing on a sandbox instance is particularly recommended if:
- You usually run a single instance of Retool.
- You have a fairly high amount of usage in your primary Retool instance(s).
- You have done a moderate to high amount of customization in your Retool apps (for example, using custom CSS, custom components) or Retool app development workflow.
- Your current version of Retool is more than 2 months (roughly 4 stable releases) behind the most recent version.
You can find instructions for spinning up a Retool instance in our deployment guide. Before you get started, though, read the important details below.
Note: If you have an existing permanent sandbox instance (i.e. an instance not depended on for day-to-day app development or app usage, whose data can be completely changed without consequences), you can use that sandbox instance instead of fully spinning up new infrastructure. You’ll likely still make use of the instructions below for seeding the instance with the latest version of your test apps.
Here are specific recommendations for the temporary instance:
The preferred way to seed this temporary Retool instance with your current apps is to connect it to a copy of your existing Retool instance’s PostgreSQL database. If you run multiple instances of Retool, select the instance that you use when developing apps. It’s important to use a copy of your existing database. Do not connect to your actual existing Retool database: it will likely be altered in the course of upgrading Retool and testing, because upgrades often include database migrations.
- To make a copy of the data: You can use the built-in PostgreSQL
pg_dumpcommand to dump the database to a file, and then you can create a new database seeded with that file. (See an example here.) However, if you are using a managed PostgreSQL database, your cloud provider likely provides a more convenient way to make a copy of the database and load it into a new database.
To allow your new temporary instance to read the copied database
In order for the new Retool instance to read the contents of the database (in particular, any sensitive secrets defined in your Resources, such as database passwords), you must set the
ENCRYPTION_KEY environment variable in the new Retool instance to the same value as in your current Retool instance.
If you are deploying on Docker, to do this in practice, you may spin up the new Retool instance as in our instructions. Then:
sudo docker-compose down
- Update the
docker.envfile to set the
ENCRYPTION_KEYto the desired value.
sudo docker-compose up -d
The initial version of the Retool software
As the starting point, you should install your current version of Retool. The easiest way to look up your current Retool version number is via the Retool UI.
- In the latest versions of Retool, the version number is displayed when you click on the “Question mark” bubble in the bottom right of the screen.
- In older versions of Retool, the version number is displayed when you click on the dropdown from your profile picture in the top right of the screen.
Fill in this version number in the deployment template files (e.g. Dockerfile) for this new instance.
The overall setup
You might opt for a simpler setup than what you usually run. Even if you usually run on Kubernetes, for the purposes of this test, you may choose to spin up the equivalent of a single AWS EC2 machine. This may be a good choice for you if you are highly confident in the mechanics of upgrading on your usual infrastructure, and primarily want to test the functionality of your Retool apps with the new Retool software.
In this step, we will run the upgrade on the temporary Retool instance. To do this, see the step-by-step instructions below in the "How-to instructions" section.
Make sure the core functionality of your apps works as expected. You may consider writing a QA checklist for these apps.
If your tests pass, you are ready to roll out the upgrade to your usual Retool instances. If you find an unexpected issue, you may reach out to the Retool Support team for assistance.
As a courtesy to your users, it’s helpful to send an additional announcement to them shortly before you begin the downtime.
If you are using the git syncing feature to sync apps across multiple Retool instances, we recommend not promoting any your apps between instances (e.g. from development to staging, or staging to production) while you do the upgrade of all your instances. You will likely want to start by upgrading your development instance, then proceed to staging, and then production.
For each of your Retool instances (if you have multiple):
- Take a backup of all of your Retool state so that you can restore it, if needed.
- Install the new version of Retool.
Below, we cover each of these steps in more detail.
Taking a backup of all your Retool state
If you are deployed on a popular cloud platform (e.g. AWS), the cloud provider may have a convenient way to backup all of the state of your running instance. (For example, AWS offers a way to backup EC2 instances as an AMI.)
If you would like to take the backup in a platform-agnostic way, here are the essential pieces:
- Retool Postgres database: If your Postgres database is managed outside of Retool, and has point-in-time recovery enabled, you already have backups. Otherwise, you may enable point-in-time recovery, or take a snapshot of the database.
- Environment variables: The most important environment variable to make sure you have stored in a safe place is the
ENCRYPTION_KEY(critical to being able to read the contents of your database). It would make sense to backup all of the environment variables specific to your Retool instance, though. For example, in a Docker deployment, you can copy the contents of your docker.env file.
- If you are using git syncing and updating your read-write instance, you can “back up” the state of the git branch before the upgrade. Simply create a new branch based off the current branch. For example, if your instance writes to a git branch called “dev”, you can create a branch that is a copy of that branch, called “dev-backup-” and push that to your git origin.
Installing the new version of Retool
To do this, see the step-by-step instructions below in the "How-to instructions" section.
As a courtesy to your users, it’s helpful to send an announcement to them to let them know they can use Retool again.
This section includes steps referenced in the above guide.
Retool releases can be pulled from Docker Hub. Exactly how you update depends on how you’ve deployed Retool.
- In the first line of the
Dockerfile, update the version number to the new version of Retool you want to upgrade to. In other words, in the line
FROM tryretool/backend:X.Y.Z, replace
X.Y.Zwith the version number.
- Then run the included update script in the
- To update Retool on Kubernetes, you can use the following command, replacing
X.Y.Zwith the version number or named tag that you’d like to update to.
kubectl set image deploy/api api=tryretool/backend:X.Y.Z
Note: If you're running a multi-container deployment of Retool, check out our guide on the order in which to upgrade your containers.
Updated 6 months ago