The best way to build internal software

Below are the instructions for deploying with Docker Compose, see our docs for more specific details for AWS, GCP, or Azure, as well as for deploying with Helm, Kubernetes, or ECS. 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 migration.

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

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

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.

1. Download and build the new images

docker compose build

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

docker compose up -d

3. Remove the old images from the system

docker image prune -a -f