Upgrade within the Retool 4.x line (Docker Compose)
Upgrade an existing self-hosted Retool 4.x Docker Compose instance to a later 4.x stable release.
This guide covers upgrading an existing self-hosted Retool Docker Compose instance that's already running Retool 4.0 or later to a later 4.x stable release (for example, 4.0 to 4.34). It doesn't cover the new-service setup (agent sandbox, JS executor, r2-agent-worker, blob storage) that a 3.x instance needs the first time it reaches 4.0.
Still running Retool 3.x? Use Upgrade from Retool 3.x to 4.0 (Docker Compose) instead.
This guide is for non-production instances only. For production, use a Kubernetes instance using Terraform blueprints.
Before you upgrade
Follow the standard upgrade best practices in addition to the steps here.
Choose your target version
Keeping your deployment up-to-date ensures your organization has access to newer features and security updates. Running a deployment that is multiple releases behind the current one makes each upgrade riskier. Changelogs accumulate more breaking changes and deprecations, incremental migration becomes harder to test, and a large version jump can skip over a release with a required migration step.
If your deployment is more than one stable release behind, upgrade through each stable release in sequence rather than jumping directly to your target version. For example, to upgrade from 3.334 to 4.86:
3.334 -> 4.0 -> 4.34 -> 4.86
Verify each installation before proceeding to the next release. Review the Stable releases or Edge releases page and read all changelogs between your current version and your target version before starting.
Upgrading sequentially through each release is another reason to keep your deployment current: the fewer releases you're behind, the fewer intermediate upgrades you need to perform.
Check for reference config changes
An incremental upgrade can require changes to your Compose file or docker.env, not only a new version, if a release added a new service or environment variable to the reference config. Pull the reference config and reconcile it against your current setup rather than overwriting it wholesale. The first command lists the images your postgres and retooldb-postgres services run, so note them before you pull:
sudo docker compose ps postgres retooldb-postgres
git stash
git fetch origin
git checkout master
git pull --rebase origin master
# Review and re-apply still necessary changes
git stash show -p
git stash sets aside your local edits, such as the version in your Dockerfile, because git pull --rebase doesn't run with uncommitted changes. git stash show -p lists what it set aside, so you can re-apply what you still need.
Preserve your existing docker.env, Dockerfile, and Compose file customizations, including your license key, SSL settings, and any custom environment variables.
PostgreSQL can't start on data from an older major version. If the reference config runs postgres or retooldb-postgres on a different PostgreSQL major version than the image you noted, set that service's image back to the one you noted. If your PostgreSQL version is older than the minimum Retool supports, upgrade PostgreSQL before you upgrade Retool.
Update your version
Set the new Retool version in your Dockerfile. The stable release is 4.86.0-stable:
ARG VERSION=X.Y.Z-stable # use your target version
ARG CLASSIC_VERSION=X.Y.Z-stable # same version, without the -hardened suffix
FROM tryretool/agent-sandbox-service:${CLASSIC_VERSION} AS agent-sandbox
FROM tryretool/code-executor-service:${VERSION} AS code-executor
FROM tryretool/js-executor-service:${CLASSIC_VERSION} AS js-executor
FROM tryretool/backend:${VERSION}
If you use hardened images, set VERSION to a hardened tag (for example, X.Y.Z-stable-hardened) for backend and code-executor-service. Hardened variants aren't available for agent-sandbox-service or js-executor-service, so keep CLASSIC_VERSION on the non-hardened tag for those two.
If you use a separate CodeExecutor.Dockerfile, update it to the same version.
Apply the AppArmor profiles
On Linux hosts with AppArmor enabled, such as Ubuntu, the agent sandbox needs Retool's docker-default AppArmor profile. Instances set up with an older version of retool-onpremise might not have it, or might lose it each time Docker restarts, and the agent sandbox fails to start without it.
Run the setup script from your retool-onpremise directory to install it, even if you ran it before:
./scripts/setup-docker-apparmor.sh
The script uses sudo if you aren't running as root. Hosts without AppArmor skip this step automatically.
On Ubuntu 24.04 and later, Code Executor also needs the usr.bin.nsjail profile. If your instance was installed before install.sh added it, follow the nsjail steps in the AppArmor README, which also explains what each profile changes.
Start the instance
Rebuild the images from your updated Dockerfile and start the instance:
sudo docker compose up -d --build
Without --build, Compose keeps using the images it built for your current version.
Compose doesn't replace agent sandbox containers, even with --build. The agent sandbox controller creates them outside Compose, so sandboxes from your previous version keep running and can be assigned to new sessions. Remove them so the controller starts new ones on your target version:
sudo docker ps -aq --filter label=com.retool.agent-executor.role=sandbox | xargs -r sudo docker rm -f
Verify all services are healthy:
sudo docker compose ps
To investigate a failing service:
sudo docker compose logs <service-name>
Verify the upgrade
Once the instance is healthy, open the profile menu in the top-right corner to confirm the version matches your target release, and spot-check your critical apps, queries, and workflows.
Rollback
If the upgrade does not go as planned:
-
Run
sudo docker compose downto stop the stack. -
Remove the agent sandbox containers. They keep running after the stack stops, and the previous version's controller can assign them to new sessions:
sudo docker ps -aq --filter label=com.retool.agent-executor.role=sandbox | xargs -r sudo docker rm -f -
Restore your
Dockerfileto the previous version and restore your backed-updocker.env, Compose file, and, if used,CodeExecutor.Dockerfile. Restoring the Compose file matters if you reconciled in a new or changed service above. Otherwise, the previous version's containers start against a topology that doesn't match it. -
Restore your PostgreSQL snapshot if the database was modified.
-
Bring the previous instance back up:
sudo docker compose up -d --build.