mirror of
https://github.com/ToolJet/ToolJet
synced 2026-04-21 21:47:17 +00:00
335 lines
12 KiB
Markdown
335 lines
12 KiB
Markdown
---
|
||
id: docker
|
||
title: Deploying ToolJet using Docker Compose
|
||
slug: /setup/docker/
|
||
sidebar_label: 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](/docs/setup/try-tooljet/).
|
||
|
||
:::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](https://github.com/ToolJet/ToolJet/tree/develop/terraform/EC2)
|
||
- Deploy on [Azure VM](https://github.com/ToolJet/ToolJet/tree/develop/terraform/Azure_VM)
|
||
- Deploy on [GCP VM](https://github.com/ToolJet/ToolJet/tree/develop/terraform/GCP)
|
||
|
||
### Installing Docker and Docker Compose
|
||
|
||
Install docker and docker-compose on the server.
|
||
|
||
- Docs for [Docker Installation](https://docs.docker.com/engine/install/)
|
||
- Docs for [Docker Compose Installation](https://docs.docker.com/compose/install/)
|
||
|
||
### 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](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA).
|
||
|
||
<!--
|
||
<Tabs>
|
||
<TabItem value="with-in-built-postgres" label="With in-built PostgreSQL" default> -->
|
||
|
||
#### 1. Download our production docker-compose file into the server.
|
||
|
||
<Tabs>
|
||
|
||
<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>
|
||
|
||
</Tabs>
|
||
|
||
#### 2. Create `.env` file in the current directory (where the docker-compose.yaml file is downloaded as in step 1):
|
||
|
||
<Tabs>
|
||
|
||
<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>
|
||
|
||
</Tabs>
|
||
|
||
#### 3. To start the docker container, use the following command:
|
||
|
||
```bash
|
||
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.
|
||
|
||
<Tabs>
|
||
|
||
<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>
|
||
|
||
</Tabs>
|
||
|
||
Also, for setting up additional environment variables in the .env file, please check our documentation on [environment variable](/docs/setup/env-vars)
|
||
|
||
### 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:
|
||
```bash
|
||
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:
|
||
```bash
|
||
./backup-restore.sh
|
||
```
|
||
<img className="screenshot-full img-full" src="/img/setup/docker/backup-and-restore.gif" alt="Docker - Backup and Restore" />
|
||
|
||
## 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](/docs/setup/workflow-temporal-to-bullmq-migration/).
|
||
:::
|
||
|
||
### Enabling Workflow Scheduling
|
||
|
||
To activate workflow scheduling, set the following environment variables:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
<details id="tj-dropdown">
|
||
|
||
<summary>Docker Compose Example with Multiple Workers and External Redis</summary>
|
||
|
||
This example shows how to run ToolJet with multiple workers and external Redis for scalable workflow processing:
|
||
|
||
```yaml
|
||
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:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
</details>
|
||
|
||
## 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](https://hub.docker.com/r/tooljet/tooljet/tags) 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):
|
||
|
||
```bash
|
||
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](https://hub.docker.com/r/tooljet/tooljet/tags) 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:
|
||
|
||
```yaml
|
||
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):
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
Docker will pull the new image and recreate the containers using the updated version.
|
||
|
||
## <br/>
|
||
|
||
## Need Help?
|
||
|
||
- Reach out via our [Slack Community](https://join.slack.com/t/tooljet/shared_invite/zt-2rk4w42t0-ZV_KJcWU9VL1BBEjnSHLCA)
|
||
- Or email us at [support@tooljet.com](mailto:support@tooljet.com)
|
||
- Found a bug? Please report it via [GitHub Issues](https://github.com/ToolJet/ToolJet/issues)
|