ToolJet/docs/versioned_docs/version-3.16.0-LTS/setup/docker.md

id	title	slug	sidebar_label
docker	Deploying ToolJet using Docker Compose	/setup/docker/	Docker

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Follow the steps below to deploy ToolJet on a server using Docker Compose. ToolJet requires a PostgreSQL database to store applications definitions, (encrypted) credentials for datasources and user authentication data.

::::info If you rather want to try out ToolJet on your local machine with Docker, you can follow the steps here.

:::warning To use ToolJet AI features in your deployment, make sure to whitelist https://api-gateway.tooljet.com and https://python-server.tooljet.com in your network settings. :::

::::

Provisioning VMs with Terraform (Optional)

If you don’t already have a server, you can use Terraform scripts to quickly spin up a VM on AWS, Azure or GCP and then deploy ToolJet with Docker.

• Deploy on AWS EC2
• Deploy on Azure VM
• Deploy on GCP VM

Installing Docker and Docker Compose

Install docker and docker-compose on the server.

• Docs for Docker Installation
• Docs for Docker Compose Installation

Deployment Options

There are two options to deploy ToolJet using Docker Compose:

1. With in-built PostgreSQL database (recommended). This setup uses the official Docker image of PostgreSQL.
2. With external PostgreSQL database. This setup is recommended if you want to use a managed PostgreSQL service such as AWS RDS or Google Cloud SQL.

Confused about which setup to select? Feel free to ask the community via Slack.

1. Download our production docker-compose file into the server.

<TabItem value="with-in-built-postgres" label="With in-built PostgreSQL" default>
  ```bash
  curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/docker-compose-db.yaml
  mv docker-compose-db.yaml docker-compose.yaml
  mkdir postgres_data
  ```
</TabItem>
<TabItem value="with-external-postgres" label="With external PostgreSQL">
  ```bash
  curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/docker-compose.yaml
  ```
</TabItem>

2. Create .env file in the current directory (where the docker-compose.yaml file is downloaded as in step 1):

<TabItem value="with-in-built-postgres" label="With in-built PostgreSQL" default>
  ```bash
  curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/.env.internal.example
  curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/internal.sh && chmod +x internal.sh
  mv .env.internal.example .env && ./internal.sh
  ```

  `internal.sh` helps to generate the basic .env variables such as the LOCKBOX_MASTER_KEY, SECRET_KEY_BASE, and the password for postgreSQL database.

</TabItem>
<TabItem value="with-external-postgres" label="With external PostgreSQL">
  Kindly set the postgresql database credentials according to your external database. Please enter the database details with the help of the bash as shown below.
  <img className="screenshot-full img-full" src="/img/setup/docker/bash.gif"/>
  ```bash
  curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/.env.external.example
  curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/external.sh && chmod +x external.sh
  mv .env.external.example .env && ./external.sh
  ```
</TabItem>

3. To start the docker container, use the following command:

docker-compose up -d

4. TOOLJET_HOST environment variable can either be the public ipv4 address of your server or a custom domain that you want to use. Which can be modified in the .env file.

Examples: TOOLJET_HOST=http://12.34.56.78 or TOOLJET_HOST=https://tooljet.yourdomain.com

If you've set a custom domain for TOOLJET_HOST, add a A record entry in your DNS settings to point to the IP address of the server.

<TabItem value="with-in-built-postgres" label="With in-built PostgreSQL" default>
  :::info
  i. Please make sure that `TOOLJET_HOST` starts with either `http://` or `https://`

  ii. Setup docker to run without root privileges by following the instructions written here https://docs.docker.com/engine/install/linux-postinstall/

  iii. If you're running on a linux server, `docker` might need sudo permissions. In that case you can either run:
  `sudo docker-compose up -d`
  :::
</TabItem>
<TabItem value="with-external-postgres" label="With external PostgreSQL">
  :::info
  i. Please make sure that `TOOLJET_HOST` starts with either `http://` or `https://`

  ii. If there are self signed HTTPS endpoints that ToolJet needs to connect to, please make sure that `NODE_EXTRA_CA_CERTS` environment variable is set to the absolute path containing the certificates.

  iii. If you're running a linux server, `docker` might need sudo permissions. In that case you can either run:
  `sudo docker-compose up -d`

  iv. Setup docker to run without root privileges by following the instructions written here https://docs.docker.com/engine/install/linux-postinstall/
  :::
</TabItem>

Also, for setting up additional environment variables in the .env file, please check our documentation on environment variable

Docker Backup (Only For In-Built PostgreSQL)

The below bash script will help with taking back-up and as well as restoring:

1. Download the script:

   curl -LO https://tooljet-deployments.s3.us-west-1.amazonaws.com/docker/backup-restore.sh && chmod +x backup-restore.sh
   

2. Run the script with the following command:

   ./backup-restore.sh
   

   

Workflows

ToolJet Workflows allows users to design and execute complex, data-centric automations using a visual, node-based interface. This feature enhances ToolJet's functionality beyond building secure internal tools, enabling developers to automate complex business processes.

:::info For users migrating from Temporal-based workflows, please refer to the Workflow Migration Guide. :::

Enabling Workflow Scheduling

To activate workflow scheduling, set the following environment variables:

# Worker Mode (required)
WORKER=true

# Workflow Processor Concurrency (optional)
TOOLJET_WORKFLOW_CONCURRENCY=5

Environment Variable Details:

• WORKER (required): Enables job processing. Set to true to activate workflow scheduling
• TOOLJET_WORKFLOW_CONCURRENCY (optional): Controls the number of workflow jobs processed concurrently per worker instance. Default is 5 if not specified

:::warning External Redis Requirement: When running separate worker containers or multiple instances, an external stateful Redis instance is required for job queue coordination. The built-in Redis only works when the server and worker are in the same container instance (single instance deployment). :::

Running Multiple Workers with External Redis

Docker Compose Example with Multiple Workers and External Redis

This example shows how to run ToolJet with multiple workers and external Redis for scalable workflow processing:

services:
  tooljet:
    tty: true
    stdin_open: true
    container_name: Tooljet-app
    image: tooljet/tooljet:ee-lts-latest
    platform: linux/amd64
    restart: always
    env_file: .env
    ports:
      - 80:80
    environment:
      SERVE_CLIENT: "true"
      PORT: "80"
    command: npm run start:prod

  tooljet-worker-1:
    container_name: tooljet-worker-1
    image: tooljet/tooljet:ee-lts-latest
    env_file: .env
    environment:
      WORKER: "true"
      TOOLJET_WORKFLOW_CONCURRENCY: 10
    command: npm run start:prod
    depends_on:
      - redis

  tooljet-worker-2:
    container_name: tooljet-worker-2
    image: tooljet/tooljet:ee-lts-latest
    env_file: .env
    environment:
      WORKER: "true"
      TOOLJET_WORKFLOW_CONCURRENCY: 10
    command: npm run start:prod
    depends_on:
      - redis

  redis:
    image: redis:7
    container_name: redis
    ports:
      - 6379:6379
    volumes:
      - redis-data:/data
    command: redis-server --appendonly yes --maxmemory-policy noeviction

volumes:
  redis-data:

Architecture:

• tooljet: Web server that handles HTTP requests and processes jobs (WORKER=true, Port 80)
• tooljet-worker-1 & tooljet-worker-2: Dedicated workers that only process workflow jobs (WORKER=true, no ports)
• redis: External stateful Redis with persistence for the job queue

Redis Environment Variables:

Add these to your .env file to connect to the external Redis:

# Redis - Note: Only REDIS_HOST and REDIS_PORT are required. Authentication and TLS are optional.
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_USER=default
REDIS_PASSWORD=
# REDIS_DB=0                   # Optional: Redis database number (default: 0)
# REDIS_TLS=false              # Optional: Enable TLS/SSL (set to 'true')

Critical Redis Configuration:

• --appendonly yes: Enables AOF (Append Only File) persistence
• --maxmemory-policy noeviction: Required by BullMQ to prevent job loss

Upgrading to the Latest LTS Version

:::info If this is a new installation of the application, you may start directly with the latest version. This upgrade guide is only for existing installations. :::

New LTS versions are released every 3-5 months with an end-of-life of atleast 18 months. To check the latest LTS version, visit the ToolJet Docker Hub page. The LTS tags follow a naming convention with the prefix LTS- followed by the version number, for example tooljet/tooljet:ee-lts-latest.

Prerequisites for Upgrading

:::warning Critical: Backup Your PostgreSQL Instance

Before starting the upgrade process, perform a comprehensive backup of your PostgreSQL instance to prevent data loss. Your backup must include both required databases:

1. PG_DB (Application Database) - Contains users, apps, and configurations
2. TOOLJET_DB (Internal Database) - Contains ToolJet Database feature data

Ensure both databases are included in your backup before proceeding with the upgrade. :::

:::warning Critical Users on versions earlier than v2.23.0-ee2.10.2 must first upgrade to this version before proceeding to the latest LTS version. :::

Upgrade Steps

After completing the PostgreSQL backup, follow the steps below to upgrade to the latest LTS version:

1. Stop the Running Containers
   Run the following command on your server (in the directory where your docker-compose.yml file is located):

   docker compose down
   

   This will stop the running containers while preserving your volumes and data.

2. Get the Latest LTS Tag from Docker Hub
   You can visit the official ToolJet Docker Hub page to get the latest image tag.

3. Update the docker-compose.yml File
   Open your docker-compose.yml file and update the image field under the tooljet service:

   services:
     tooljet:
       image: tooljet/tooljet:v3.x.x-lts # Replace with the latest LTS tag
   

   :::note Replace v3.x.x-lts with the exact LTS version tag copied from Docker Hub. :::

4. Start ToolJet with the New Version
   After updating the image tag in your docker-compose.yml file, run the following command on your server (in the same directory):

   docker compose up -d
   

   Docker will pull the new image and recreate the containers using the updated version.

Need Help?

• Reach out via our Slack Community
• Or email us at support@tooljet.com
• Found a bug? Please report it via GitHub Issues