Skip to main content

Upgrade your Docker Compose deployment

Upgrade an existing self-hosted Retool Docker Compose deployment to self-hosted Retool 4.0 and later.

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, this guide explains how to upgrade and add the necessary services.

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.

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​

ChangeDetails
New servicesThree new services are added: js-executor, agent-sandbox, and r2-worker. These are included in the reference docker-compose.yml and start automatically after the upgrade.
Blob storage is requiredObject 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 requiredThe new services require significantly more CPU and memory. Plan for at least 8 vCPUs and 64 GiB on the VM.
Temporal required for agentsThe agent Temporal worker requires a Temporal cluster. If you do not have one, configure Temporal Cloud after deployment.

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.

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.

ServiceIncluded in reference configAction required
JS ExecutorYes, added by defaultNone; works out of the box
Agent SandboxYes, added by defaultNone; works out of the box
Blob storageYes (bundled MinIO)Recommended: switch to a cloud object store for non-trivial use
Temporal + agent Temporal workerDepends on existing setupChoose 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.0.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}

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​

Run install.sh from the updated repository to add the required new environment variables to your existing docker.env:

./install.sh

This adds the new environment variables while preserving your existing values, including ENCRYPTION_KEY and LICENSE_KEY.

After running it, review docker.env and confirm the following are set correctly.

Blob storage​

Set the provider and credentials for your chosen object store:

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

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

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. Set up Retool AI. Navigate to Settings → AI to enable Assist, then go to Resources → AI to configure your AI provider keys.

Retool-managed AI keys are not compatible with self-hosted deployments. The managed key proxy has a 29-second timeout; many agent operations exceed this and will fail silently. Configure your own API keys (Bring Your Own Key) under Resources → AI.

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.