Upgrade from Retool 3.x to 4.0 (Docker Compose)

Upgrade an existing self-hosted Retool 3.x Docker Compose deployment to Retool 4.0.

Additional requirements introduced in Retool 4.0 include more services and resources. If you have an existing Docker Compose-based staging deployment of self-hosted Retool running 3.x, this guide explains how to upgrade and add the necessary services.

note

Already running Retool 4.0 or later? Use Upgrade within the Retool 4.x line (Docker Compose) instead — this guide's steps are one-time setup for the 3.x → 4.0 transition and don't apply to later 4.x upgrades.

The upgrade will likely require a larger VM. Plan for a maintenance window and read the whole guide before you start.

This guide is for non-production deployments only. For production, migrate to a Kubernetes deployment using Terraform blueprints.

note

Retool's officially supported deployment configurations are Helm on Kubernetes and the Docker Compose blueprints. This guide is provided for convenience, but Retool does not provide support guarantees for deployments outside of those configurations. If you are running Docker Compose in production, contact your account team about migrating to a Kubernetes deployment.

Reference configuration files live in the tryretool/retool-onpremise repository.

What changed from Retool 3.x

Change	Details
New services	Four new services are added: js-executor, agent-sandbox, r2-worker, and mcp. These are included in the reference docker-compose.yml and start automatically after the upgrade.
Blob storage is required	Object storage (S3, Azure Blob, or GCS) is a platform requirement. The reference config includes a bundled MinIO container for non-production use, but production deployments should use a cloud object store.
VM size increase required	The new services require significantly more CPU and memory. Plan for at least 8 vCPUs and 64 GiB on the VM.
Temporal required for agents	The agent Temporal worker requires a Temporal cluster. If you do not have one, configure Temporal Cloud after deployment.
MCP server requires manual configuration on upgrade	The mcp service needs three docker.env variables that install.sh only writes on a fresh install. Add them manually (refer to MCP server below) or MCP clients can't authenticate.

Before you start

Use this checklist as you prepare the upgrade to ensure you have everything ready.

Follow the standard upgrade best practices in addition to the steps here. Perform the migration during off-peak hours.

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.

Services overview

This upgrade adds several services to your stack. Some work out of the box; others require a decision or external infrastructure before you start.

Service	Included in reference config	Action required
JS Executor	Yes, added by default	None; works out of the box
Agent Sandbox	Yes, added by default	None; works out of the box
Blob storage	Yes (bundled MinIO)	Recommended: switch to a cloud object store for non-trivial use
MCP server	Yes, added by default	Required: add three docker.env variables manually (refer to MCP server below)
Temporal + agent Temporal worker	Depends on existing setup	Choose a Temporal path (refer to Temporal below)

For a full description of each service, refer to the architecture overview.

Blob storage

The reference configuration includes a MinIO container that provides working blob storage with no external dependencies. For development and POC environments, no additional configuration is needed. For any meaningful use, switch to a cloud object store (S3, Azure Blob, or GCS). The bundled MinIO container uses local VM disk, which will eventually run out of space.

Temporal

The agent Temporal worker requires a Temporal cluster:

• You already have a Temporal cluster: Use your existing cluster, even if it runs locally in your stack. Point the new worker at the same cluster using the Temporal environment variables in Configure the new environment variables.
• You do not have Temporal: Retool recommends Temporal Cloud. Configure it via the in-product setup after deployment (click the Workflows nav item). Temporal Cloud requires outbound egress on ports 443 and 7233. Refer to Temporal egress.

CPU and memory requirements

These services consume meaningful additional CPU and memory. You will most likely need to resize your VM before starting.

For a Retool 4.0 deployment, plan for at least 8 vCPUs and 64 GiB memory. If your current VM is smaller than this, resize it before proceeding.

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 the tag shown above

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.

Replace X.Y.Z-stable with the stable version from the release notes. If you use a separate CodeExecutor.Dockerfile, update it to the same version.

Pull the latest configuration files

The updated configuration adds the new services to your Compose stack. How you pull it depends on how you manage the repository.

If you cloned the repository

git fetch origin
git checkout main
git pull origin main

If you did not clone the repository

Download the latest directly:

curl -L https://github.com/tryretool/retool-onpremise/archive/refs/heads/main.zip \
  -o retool.zip
unzip retool.zip

Preserve your customizations

Do not overwrite your existing docker.env, Dockerfile, or docker-compose.yml wholesale. Reconcile the updated reference files against your current setup to keep your version pin, license key, SSL settings, and any custom environment variables.

Configure the new environment variables

install.sh only initializes docker.env for a fresh install. It exits immediately without making changes if docker.env already exists, so it can't add the new variables below to an existing deployment. Add them to your existing docker.env manually instead, alongside your current values, including ENCRYPTION_KEY and LICENSE_KEY.

Review docker.env and confirm the following are set correctly.

Blob storage

Set the provider and credentials for your chosen object store:

Amazon S3

RR_BLOB_STORAGE_PROVIDER=s3
RR_DEFAULT_S3_BUCKET=<your-bucket>
RR_DEFAULT_S3_ACCESS_KEY_ID=<your-key-id>
RR_DEFAULT_S3_SECRET_ACCESS_KEY=<your-secret-key>
RR_DEFAULT_S3_REGION=<your-region>
RR_DEFAULT_S3_ENDPOINT=             # optional; for S3-compatible stores

Azure Blob

RR_BLOB_STORAGE_PROVIDER=azure
RR_DEFAULT_AZURE_CONNECTION_STRING=<your-connection-string>
RR_DEFAULT_AZURE_CONTAINER=<your-container>

GCS

RR_DEFAULT_GCS_CREDENTIALS must be a JSON string for a GCP service account with roles/storage.objectAdmin and roles/storage.bucketViewer.

RR_BLOB_STORAGE_PROVIDER=gcs
RR_DEFAULT_GCS_CREDENTIALS=<json-string>
RR_DEFAULT_GCS_BUCKET=<your-bucket>

If you are using the bundled MinIO for development, no additional blob storage configuration is needed.

MCP server

The updated configuration adds an mcp service that serves Retool's MCP server at /mcp. It requires HTTPS and three variables in docker.env that install.sh only writes on a fresh install:

# Public host serving OAuth metadata and /api/oauth2/* (your Retool domain, no scheme)
OAUTH_MAIN_DOMAIN=<your-domain>
# Public base URL the MCP server is reachable on, used for import upload URLs
MCP_SERVICE_EXTERNAL_URL=https://<your-domain>
# Shared secret the MCP server presents to the backend's /api/oauth2/introspect.
# Read by both the api and mcp services, so it must match on both.
OAUTH_INTROSPECTION_AUTH_TOKEN=<generate-a-random-value>

Without these variables, the mcp container still starts, but MCP clients fail to authenticate. If you don't want to expose an MCP server, remove the mcp service block from docker-compose.yml instead.

Temporal

If you use an existing Temporal cluster, uncomment the include block in compose.yaml and confirm the connection variables are present in docker.env:

WORKFLOW_TEMPORAL_CLUSTER_FRONTEND_HOST=<host>
WORKFLOW_TEMPORAL_CLUSTER_FRONTEND_PORT=<port>
WORKFLOW_TEMPORAL_CLUSTER_NAMESPACE=<namespace>

If using Temporal Cloud (mTLS), also set the WORKFLOW_TEMPORAL_TLS_* variables.

If you do not have an existing Temporal cluster, leave temporal.yaml disabled (the default). Configure Temporal via the in-product setup after deployment.

Start the updated deployment

Bring the stack up:

sudo docker compose up -d

The initial start can take several minutes as new service images are pulled and first-time setup runs.

Verify all services are healthy:

sudo docker compose ps

Confirm these services (JS Executor, Agent Sandbox, the agent Temporal worker, and MinIO if used) are running alongside your existing containers. If any service is restarting repeatedly or being OOM-killed, the VM likely needs more memory (refer to CPU and memory requirements).

To investigate a failing service:

sudo docker compose logs <service-name>

Complete setup in the Retool UI

Once the deployment is healthy, an admin user should complete the following in the Retool interface:

1. Enable Temporal. Navigate to Workflows and follow the in-product setup steps. A valid license key is required.
2. Configure your organization to use the new app builder.

Rollback

If the migration 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.
3. Restore your PostgreSQL snapshot if the database was modified.
4. Bring the previous deployment back up: sudo docker compose up -d.