The best way to build internal software

Below are the instructions for deploying with Docker Compose, see our docs for more specific details, including deploying with Kubernetes or Helm. Check out our Community Forums if you have questions or issues, and see our deprecated-onpremise repo if you need to reference legacy deployment instructions.

Deploy with Docker Compose

Install → Configure → Run → Upgrade

Install

Important

We test and support running on Ubuntu. If on a different platform, you may need to manually install requirements like Docker.

1. Download this repo

git clone https://github.com/tryretool/retool-onpremise retool && cd retool

2. Run our install script to attempt to set up Docker and initialize the .env files

./install.sh

The script will create docker.env and retooldb.env if successful, else it should call out potential issues to address before rerunning.

Warning

We now assume Compose v2 is installed as a plugin accessed through docker compose, we no longer use the legacy v1 docker-compose syntax. You may need to use the latter based on your OS and installation, see Docker's docs for more context on the versions.

Configure

Tip

Optionally run sudo usermod -aG docker $USER and log out/back in to not require sudo for every Docker command moving forward. Not required, but we'll assume this in the guide

1. Check the generated .env files to make sure the license key and randomized keys were set as expected during the installation.

2. Review the blob storage settings in docker.env. The generated defaults use bundled MinIO through RR_BLOB_STORAGE_PROVIDER=s3 and RR_DEFAULT_S3_* variables. For production, replace these with your external object store credentials. For AWS S3, remove RR_DEFAULT_S3_ENDPOINT and AWS_ENDPOINT_URL; for S3-compatible providers such as MinIO, set both endpoint variables to the provider endpoint.

3. Save off the ENCRYPTION_KEY value, since this is needed to encrypt/decrypt values saved into the Postgres database the Retool instance runs on.

4. Replace X.Y.Z-stable in Dockerfile with the desired Retool version listed in our Dockerhub repo, we recommend the latest patch of the most recent stable version.

5. To set up HTTPS, you'll need your domain pointing to your server's IP address. If that's in place, make sure DOMAINS is correct in docker.env, and then set STAGE=production in compose.yaml for the https-portal container to attempt to get and use a free Let's Encrypt cert for your domain on startup.

Warning

You must set COOKIE_INSECURE=true in docker.env to allow logging into Retool without HTTPS configured (not recommended)

6. By default, the deployment will include a Temporal container for Workflows. If you have an Enterprise license and would like to instead use Retool's managed Temporal cluster, comment out the include block in compose.yaml and the WORKFLOW_TEMPORAL_... environment variables in docker.env. Check out our docs for more information on Temporal deployment options.

7. The deployment includes an mcp container that serves Retool's MCP server at /mcp, letting external MCP clients connect to your instance. It needs HTTPS and the OAUTH_MAIN_DOMAIN, MCP_SERVICE_EXTERNAL_URL, and OAUTH_INTROSPECTION_AUTH_TOKEN variables in docker.env (all set by install.sh). The https-portal container routes /mcp to it via CUSTOM_NGINX_SERVER_CONFIG_BLOCK; the OAuth metadata and introspection endpoints it depends on are served by the api service. To disable MCP, remove the mcp service and that nginx block from compose.yaml. Point your MCP client at https://<your-domain>/mcp.

Run

1. Bring up containers

docker compose up -d

2. Check your container statuses after a few minutes

docker compose ps

3. Check your container logs if any container isn't up and running

docker compose logs

4. Go to your domain or IP in a browser and click Sign up to initialize and log into the new instance

Upgrade

Pull the latest master of this repo first, so you have the newest scripts and compose.yaml. Before you pull, note the images your postgres and retooldb-postgres services run, and stash your local changes, such as the version you set in Dockerfile, because git pull --rebase won't run with uncommitted changes:

docker compose ps postgres retooldb-postgres
git stash
git pull --rebase origin master

# Review and re-apply still necessary changes
git stash show -p

Then set the new version in Dockerfile, and either run ./upgrade.sh or follow the below steps:

Warning

PostgreSQL can't start on data from an older major version. If the new compose.yaml 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 is older than the minimum Retool supports, upgrade it before you upgrade Retool. RetoolOS search needs pgvector, which the reference postgres image includes. If your postgres image doesn't include it, leave RETOOLOS_SEARCH_ENABLED off, or Retool won't start.

Note

The mcp service reads OAUTH_MAIN_DOMAIN, MCP_SERVICE_EXTERNAL_URL, and OAUTH_INTROSPECTION_AUTH_TOKEN from docker.env. install.sh only writes these on a fresh install, so if you are upgrading an existing deployment add them yourself (see step 7 under Configure). Without them the mcp container still starts but MCP clients fail to authenticate.

Note

On hosts with AppArmor, such as Ubuntu, the agent sandbox needs the bundled docker-default AppArmor profile. Installs set up with an older install.sh don't have it, and without it the agent sandbox fails to start. ./upgrade.sh installs it when it's missing. On Ubuntu 24.04 and later, Code Executor also needs the usr.bin.nsjail profile, which upgrade.sh doesn't install. If your install predates it, follow the nsjail steps in appArmor/README.md.

1. Install or reapply the agent sandbox's AppArmor profile. This skips hosts without AppArmor. On hosts with AppArmor, it reloads the profile even when already installed and requires sudo for non-root users.

./scripts/setup-docker-apparmor.sh

2. Download and build the new images

docker compose build

3. Bring up the new containers to replace the old ones

docker compose up -d

4. Remove the agent sandbox containers. The agent sandbox controller creates them outside Compose, so step 3 doesn't replace them, and it can assign the old version's to new sessions. It starts new ones on the new version.

docker ps -aq --filter label=com.retool.agent-executor.role=sandbox | xargs -r docker rm -f

5. Remove the old images Compose built for this deployment. Compose labels each image it builds with the project name, so other images on the host stay.

docker image prune -a -f --filter "label=com.docker.compose.project=$(docker compose config | sed -n 's/^name: //p')"