ToolJet Deployment & Usage Guide

1. Prerequisites

Before deploying ToolJet, ensure you have the following installed:

Docker & Docker Compose: Required for the easiest local and production deployment. ToolJet is distributed as a Docker image.
Node.js & npm/yarn: Required only if you plan to build the frontend from source or contribute to development. Version 16+ is recommended.
Git: To clone the repository.
A PostgreSQL database: ToolJet requires an external PostgreSQL database (version 13+). The Docker quickstart uses an internal volume, but for production, a managed or external database is strongly recommended.
Redis (Optional but Recommended): For production deployments with multiple instances, Redis is required for caching and session management.

2. Installation

Quickstart with Docker (Recommended for Testing)

Run the following command to start ToolJet with a persistent data volume:

docker run \
  --name tooljet \
  --restart unless-stopped \
  -p 80:80 \
  --platform linux/amd64 \
  -v tooljet_data:/var/lib/postgresql/13/main \
  tooljet/try:ee-lts-latest

This command pulls the latest LTS (Long-Term Support) image, which is recommended for stability.
Access the application at http://localhost.
The first user to sign up becomes the super admin.

Installation from Source (For Development/Custom Builds)

Clone the repository:

git clone https://github.com/ToolJet/ToolJet.git
cd ToolJet

Set up environment variables: Create a .env file in the root directory. See the Configuration section for required variables.

Install dependencies and build:

# Install backend dependencies
npm install --prefix server

# Install frontend dependencies
npm install --prefix frontend

# Build the frontend
npm run build --prefix frontend

Start the development server:
```
npm run dev --prefix server
```
The server will start on http://localhost:3000 by default.

3. Configuration

ToolJet is configured via environment variables. For Docker deployments, these are passed with the -e flag or defined in a .env file used with docker-compose.

Essential Environment Variables

Variable	Description	Required	Default
`PG_HOST`	PostgreSQL host address.	Yes (if not using internal Docker volume)
`PG_PORT`	PostgreSQL port.	No	`5432`
`PG_DB`	PostgreSQL database name.	Yes	`tooljet`
`PG_USER`	PostgreSQL username.	Yes	`tooljet`
`PG_PASS`	PostgreSQL password.	Yes
`NODE_ENV`	Environment (`production` or `development`).	No	`production`
`SECRET_KEY_BASE`	Critical. Secret key for encrypting sensitive data (queries, constants, secrets). Must be a long, random string.	Yes (Production)	Auto-generated in dev
`LOCKBOX_MASTER_KEY`	Critical. 32-byte hex string for encrypting database fields. Generate with `openssl rand -hex 32`.	Yes (Production)
`REDIS_HOST`	Redis host for caching/sessions.	Recommended for production/scaling
`REDIS_PORT`	Redis port.	No	`6379`
`REDIS_PASSWORD`	Redis password.	No
`SERVICE_TOKEN`	Token for internal service-to-service communication.	Yes	Auto-generated if missing
`APP_MAX_AGE`	Session cookie max age in seconds.	No	`1209600` (14 days)

Example `.env` file for Production (Docker)

NODE_ENV=production
PG_HOST=your-postgres-host.rds.amazonaws.com
PG_PORT=5432
PG_DB=tooljet_prod
PG_USER=tooljet_admin
PG_PASS=your_secure_password
SECRET_KEY_BASE=your_very_long_random_secret_string_here_min_64_chars
LOCKBOX_MASTER_KEY=your_32_byte_hex_string_here
REDIS_HOST=your-redis-host
REDIS_PORT=6379
SERVICE_TOKEN=another_random_service_token

Note: For the Docker quickstart command, a default internal PostgreSQL volume is used, and essential keys are auto-generated. For any production or persistent deployment, you must set SECRET_KEY_BASE and LOCKBOX_MASTER_KEY manually. Changing these keys after data has been encrypted will render existing data unreadable.

4. Build & Run

Running in Production (Docker)

Use the official Docker image with your configured environment variables:

docker run -d \
  --name tooljet \
  --restart unless-stopped \
  -p 80:80 \
  -e PG_HOST=your-db-host \
  -e PG_USER=your-db-user \
  -e PG_PASS=your-db-pass \
  -e PG_DB=tooljet \
  -e SECRET_KEY_BASE=your_secret_key \
  -e LOCKBOX_MASTER_KEY=your_lockbox_key \
  -v tooljet_uploads:/app/uploads \
  tooljet/try:ee-lts-latest

Persistent Storage: Always mount a volume for /app/uploads to persist user-uploaded files (images, files).

Running in Development (from source)

Ensure your .env file is set up (you can copy .env.example if available).
Start the backend server in watch mode:
```
npm run dev --prefix server
```
In a separate terminal, start the frontend development server:
```
npm run start --prefix frontend
```
Access the app at http://localhost:3000.

5. Deployment

ToolJet is designed for containerized deployment. The official Docker image (tooljet/try:ee-lts-latest) can be deployed on any platform that supports Docker containers.

Recommended Platforms

Kubernetes: Use the official Helm chart. See the Helm deployment guide.
AWS: Deploy on ECS (Elastic Container Service) or EKS (Elastic Kubernetes Service). See the AWS ECS and AWS EKS guides.
DigitalOcean: Use the App Platform or a Droplet with Docker. See the DigitalOcean guide.
Google Cloud Platform (GCP): Deploy on Cloud Run or GKE (Google Kubernetes Engine).
Azure: Deploy on Azure Container Instances (ACI) or AKS (Azure Kubernetes Service).
OpenShift: Supported via the standard Docker/Helm deployment. See the OpenShift guide.

General Deployment Steps (Any Platform)

Provision a PostgreSQL database (managed service like RDS, CloudSQL, or a self-hosted instance). Note the connection string.
Provision a Redis instance (ElastiCache, Memorystore, etc.) if scaling beyond one instance.
Generate strong, random values for SECRET_KEY_BASE and LOCKBOX_MASTER_KEY.
Configure environment variables in your deployment platform (Docker -e flags, Kubernetes Secrets/ConfigMaps, ECS Task Definition, etc.).
Deploy the ToolJet Docker container, ensuring:
- Port 80 (or your chosen host port) is exposed.
- A persistent volume is mounted to /app/uploads.
- The container has network access to your PostgreSQL and Redis instances.
Access the deployment URL and sign up with the first user to become the super admin.

6. Troubleshooting

Common Issues & Solutions

Issue	Solution
"Cannot connect to database" error on startup	1. Verify `PG_HOST`, `PG_PORT`, `PG_USER`, `PG_PASS`, `PG_DB` are correct.<br>2. Ensure the PostgreSQL server is running and accessible from the ToolJet container.<br>3. Check if a firewall or security group is blocking the connection.
"Invalid master key" or data decryption failures	You are using a different `LOCKBOX_MASTER_KEY` or `SECRET_KEY_BASE` than the one used when the data was encrypted. You must use the original keys. If lost, encrypted data (app queries, constants, secrets) cannot be recovered. You must reset the database or start fresh.
Application starts but shows a blank page / missing CSS	The frontend build assets may not be present. If running from source, ensure you ran `npm run build --prefix frontend`. If using Docker, the official image includes built assets. Check container logs for static file serving errors.
File uploads fail or are lost after restart	You did not mount a persistent volume to `/app/uploads`. Add `-v /host/path:/app/uploads` to your `docker run` command or configure a volume in your orchestration platform.
Performance is slow / high memory usage	1. Ensure you have allocated sufficient resources (CPU/Memory) to the container.<br>2. For production, Redis must be configured (`REDIS_HOST`). Without Redis, ToolJet falls back to in-memory caching, which doesn't scale and can cause memory leaks in multi-instance setups.<br>3. Check database connection pool settings.
"Service token is missing" error	The `SERVICE_TOKEN` environment variable is not set. Generate a random string and set it. This token is used for secure internal API calls.
Cannot sign up / "User already exists" on first run	The first user sign-up creates the super admin. If you've already signed up once and want to reset, you must either: 1) Delete the database and start fresh, or 2) Manually promote an existing user to admin via the database (not recommended).

Getting Logs

Docker: docker logs tooljet
Kubernetes: kubectl logs <pod-name> -n <namespace>
From source (dev): Logs are printed to the terminal where npm run dev is running.

Further Help

Consult the official documentation: https://docs.tooljet.com
Search existing GitHub Issues.
Join the ToolJet Community Slack for real-time support.

How to Deploy & Use ToolJet