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-worker, blob storage) that a 3.x instance needs the first time it reaches 4.0.

note

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.300 to 4.34:

3.300 -> 3.334 -> 4.0 -> 4.34

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.

Update your version

Set the new Retool version in your Dockerfile. The stable release is 4.34.0-stable:

ARG VERSION=X.Y.Z-stable  # use your target version

FROM tryretool/agent-sandbox-service:${VERSION} AS agent-sandbox
FROM tryretool/code-executor-service:${VERSION} AS code-executor
FROM tryretool/js-executor-service:${VERSION} AS js-executor
FROM tryretool/backend:${VERSION}

If you use hardened images, append -hardened to the backend tag only (for example, X.Y.Z-stable-hardened). Hardened variants aren't yet available for agent-sandbox-service, code-executor-service, or js-executor-service, so those keep the classic tag.

If you use a separate CodeExecutor.Dockerfile, update it to the same version.

Check for reference config changes

An incremental upgrade can still require docker-compose.yml or docker.env changes beyond the version bump, 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:

git fetch origin
git checkout main
git pull origin main

Preserve your existing docker.env, Dockerfile, and docker-compose.yml customizations, including your license key, SSL settings, and any custom environment variables.

Start the instance

sudo docker compose up -d

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:

1. Run sudo docker compose down to stop the stack.
2. Restore your Dockerfile to the previous version and restore your backed-up docker.env, docker-compose.yml, and, if used, CodeExecutor.Dockerfile. Restoring docker-compose.yml 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.
3. Restore your PostgreSQL snapshot if the database was modified.
4. Bring the previous instance back up: sudo docker compose up -d.