ToolJet

​

Overview

​

Architecture

• ToolJet server — A standard HTTP workload serving the UI and REST API on port 3000. It runs its database migrations automatically on boot and scales horizontally through tooljet.replicas. PostgREST (which serves the ToolJet Database API) and a single-instance fallback Redis are bundled inside the official image, so no extra workloads are deployed for them.
• PostgreSQL — The postgres template as a subchart. A single instance holds two databases, both created automatically on first boot: tooljet (apps, users, and encrypted datasource credentials) and tooljet_db (the ToolJet Database, served through the in-image PostgREST). ToolJet’s boot scripts also create a sample_db with sample data.
• Redis + Sentinel (optional) — The redis template as a subchart, pinned to one data node and one sentinel. It carries the shared job queue and multiplayer coordination between replicas, and is required whenever tooljet.replicas is 2 or more.

​

What Gets Created

• Standard ToolJet Workload — The ToolJet server on port 3000 ({release}-tooljet), with tooljet.replicas replicas and configurable CPU and memory.
• Stateful PostgreSQL Workload — One PostgreSQL instance from the subchart, with its own volume set (10 GiB by default).
• Redis and Sentinel Workloads (optional) — One Redis data node and one sentinel, created when redis.enabled is true.
• Secret — A template-created dictionary secret ({release}-tooljet-db) holding the database username and password used to assemble ToolJet’s PG_*, TOOLJET_DB_*, and PGRST_DB_URI settings. Your prerequisite key secret is not created by the template — see Prerequisites.
• Identity & Policy — An identity bound to the ToolJet workload, and a policy granting it reveal on exactly the secrets it reads: the database secret, your prerequisite key secret, and — when configured — the SMTP and Redis password secrets.

​

Prerequisites

cpln secret create-dictionary --name my-tooljet-secrets \
  --entry SECRET_KEY_BASE=$(openssl rand -hex 64) \
  --entry LOCKBOX_MASTER_KEY=$(openssl rand -hex 32) \
  --entry PGRST_JWT_SECRET=$(openssl rand -hex 32)

​

First Run

​

Configuration

tooljet:
  image: tooljet/tooljet:v3.20.204-lts
  replicas: 1 # >=2 requires redis.enabled=true (shared job queue + multiplayer coordination)
  host: "" # public base URL ToolJet advertises, with https://; empty = derive from the canonical endpoint
  resources:
    minCpu: 500m
    maxCpu: 2000m
    minMemory: 1Gi
    maxMemory: 4Gi # first-boot migrations OOM below this (the image bakes a 4096MB Node heap)

secrets:
  name: my-tooljet-secrets # dictionary secret with the three keys — MUST exist before install

smtp:
  enabled: false # only takes effect at INITIAL install (see Email)
  host: smtp.example.com
  port: 587
  fromEmail: no-reply@example.com
  auth:
    secretName: "" # optional dictionary secret with SMTP_USERNAME + SMTP_PASSWORD; empty = unauthenticated relay

publicAccess:
  enabled: true # HTTPS UI + API on the auto *.cpln.app endpoint; false = internal-only

internalAccess:
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used only with workload-list, e.g. //gvc/GVC_NAME/workload/WORKLOAD_NAME

postgres: # app DB + ToolJet Database
  image: postgres:16
  config:
    username: tooljet
    password: change-me-tooljet-pg # change before installing
    database: tooljet # tooljet_db is auto-created alongside it
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

redis: # optional — required for tooljet.replicas >= 2
  enabled: false
  redis:
    image: redis:7.4
    replicas: 1 # keep at 1 — ToolJet is not Sentinel-aware
    auth:
      password:
        enabled: false # true = require AUTH, wired into ToolJet as REDIS_PASSWORD
        value: change-me-tooljet-redis
    resources:
      cpu: 200m
      memory: 256Mi
      minCpu: 80m
      minMemory: 128Mi
  sentinel:
    image: redis:7.4
    replicas: 1 # monitor only
    resources:
      cpu: 200m
      memory: 256Mi
      minCpu: 80m
      minMemory: 128Mi

​

ToolJet Server

• image — The official ToolJet LTS image.
• replicas — Number of ToolJet replicas. Anything above 1 requires redis.enabled: true; the chart fails the render with a clear message otherwise.
• host — The public base URL ToolJet advertises in links and redirects, including the https:// scheme. Leave it empty to derive it from the workload’s canonical endpoint; set it when you serve ToolJet on a custom domain.
• resources — CPU and memory bounds for the ToolJet container.

​

Databases

​

Scaling

tooljet:
  replicas: 2
redis:
  enabled: true

• redis.enabled — Deploys the redis subchart and points ToolJet at it. When disabled, a single-replica ToolJet uses the Redis inside its own container.
• redis.redis.auth.password.enabled / .value — Require AUTH on the Redis data node and wire the password into ToolJet. When enabled, the password is stored in a template-created secret that the ToolJet identity is granted reveal on.
• redis.redis.resources / redis.sentinel.resources — CPU and memory bounds for the Redis and sentinel containers.

​

Access

• publicAccess.enabled — Serve the UI and API on the auto-assigned *.cpln.app HTTPS endpoint (default). Set to false for an internal-only instance: external requests are then refused at the edge, and in-GVC callers still reach it per internalAccess.
• internalAccess.type — Controls which workloads can reach ToolJet over the internal network:

​

Email

smtp:
  enabled: true
  host: smtp.example.com
  port: 587
  fromEmail: no-reply@example.com
  auth:
    secretName: my-tooljet-smtp # dictionary secret with SMTP_USERNAME + SMTP_PASSWORD

cpln secret create-dictionary --name my-tooljet-smtp \
  --entry SMTP_USERNAME=apikey --entry SMTP_PASSWORD=YOUR_PASSWORD

​

Connecting

​

Important Notes

• Create the key secret before installing — secrets.name must point at an existing dictionary secret with SECRET_KEY_BASE, LOCKBOX_MASTER_KEY, and PGRST_JWT_SECRET. A missing secret pauses the deployment until the secret is created.
• SECRET_KEY_BASE and LOCKBOX_MASTER_KEY are write-once — rotating LOCKBOX_MASTER_KEY makes every stored datasource credential undecryptable. Back the keys up outside Control Plane.
• Do not lower tooljet.resources.maxMemory below 4Gi — the first boot’s migrations run out of memory below it and the workload never becomes ready.
• Claim the Super Admin account right after install — the first visitor to complete onboarding owns the instance.
• Configure SMTP at initial install — enabling it via a later upgrade silently does nothing.
• tooljet.replicas of 2 or more requires redis.enabled: true, and both the Redis data node and sentinel must stay at one replica.
• Change postgres.config.password before installing — it seeds the database on first boot and is not updated by later value edits.
• All ToolJet state lives in PostgreSQL — apps, users, and ToolJet Database tables survive restarts and upgrades. Uninstalling deletes the database volume set and everything in it.
• ToolJet is licensed under the AGPL — the deployed image is the LTS build and runs the free tier without a license key.

​

External References