Chatwoot

Overview

Chatwoot is an open-source customer engagement platform — an embeddable live-chat widget, a shared email inbox, and an omnichannel agent desk in one application. This template deploys the Community Edition (-ce image, MIT core): a Rails web tier serving the dashboard, REST API, widget and WebSockets on port 3000, a Sidekiq worker that also runs database migrations, a bundled single-node Redis, and a pgvector-capable PostgreSQL — highly available by default, or single-instance with one flag. Attachments go to a persistent volume or to object storage.

This template does not create a GVC. It deploys into an existing GVC that you already have; pass it with --gvc GVC_NAME.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-chatwoot`	Rails web tier — dashboard, API, chat widget and WebSockets (stateful, `chatwoot.replicas` replicas, port `3000`)	—
Workload	`RELEASE_NAME-chatwoot-worker`	Sidekiq worker; also runs migrations and the first-run bootstrap (standard, fixed at 1 replica)	—
Workload	`RELEASE_NAME-chatwoot-redis`	Bundled Redis — queues, live updates, cache (stateful, fixed at 1 replica, port `6379`)	—
Workload	`RELEASE_NAME-postgres-ha`	Patroni PostgreSQL cluster, pgvector included (stateful, `postgresHA.replicas` replicas)	`postgresHA.enabled: true` (default)
Workload	`RELEASE_NAME-etcd`	etcd consensus store for Patroni (stateful)	`postgresHA.enabled: true` (default)
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy leader endpoint Chatwoot connects to (standard)	`postgresHA.enabled: true` (default)
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled logical database backup (cron)	`postgresHA.backup.enabled: true` with `mode: logical`
Workload	`RELEASE_NAME-postgres`	Single-instance PostgreSQL on a pgvector image (stateful)	`postgres.enabled: true`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled logical database backup (cron)	`postgres.backup.enabled: true`
Volume Set	`RELEASE_NAME-chatwoot-storage`	Local attachments at `/app/storage`	`storage.type: local` (default)
Volume Set	`RELEASE_NAME-chatwoot-redis-vs`	Redis append-only file at `/data`	—
Volume Set	`RELEASE_NAME-postgres-ha-vs`, `RELEASE_NAME-etcd-vs`	Database and etcd data, one volume per replica	`postgresHA.enabled: true` (default)
Volume Set	`RELEASE_NAME-pg-vs`	Single-instance database data	`postgres.enabled: true`
Secret	`my-chatwoot-db-credentials`	Dictionary secret with the database `username`, `password` and `database`, built by this template from `postgres.credentials.*`; the name comes from `postgresHA.config.credentialsSecretName` or `postgres.config.credentialsSecretName`	—
Secret	`RELEASE_NAME-chatwoot-creds`	Dictionary secret holding the bundled Redis password	—
Secret	`RELEASE_NAME-chatwoot-web-start`, `RELEASE_NAME-chatwoot-worker-start`	Start scripts for the web and worker containers	—
Secret	`RELEASE_NAME-etcd-startup`, `RELEASE_NAME-patroni-startup`, `RELEASE_NAME-postgres-proxy-startup`, `RELEASE_NAME-wal-g-backup-script`	Start scripts of the highly available database	`postgresHA.enabled: true` (default)
Secret	`RELEASE_NAME-postgres-config`	Non-sensitive backup settings of the highly available database	`postgresHA.backup.enabled: true`
Identity	`RELEASE_NAME-chatwoot-identity`	Shared by the web and worker workloads; carries the AWS cloud account link when `storage.type: s3`	—
Policy	`RELEASE_NAME-chatwoot-policy`	Grants the identity `reveal` on exactly the secrets Chatwoot reads, including your prerequisite secrets	—
Identity, Policy	`RELEASE_NAME-postgres-ha-identity`, `RELEASE_NAME-postgres-ha-policy`, `RELEASE_NAME-etcd-identity`, `RELEASE_NAME-etcd-policy`	Database and etcd identities and their secret access	`postgresHA.enabled: true` (default)
Identity, Policy	`RELEASE_NAME-pg-identity`, `RELEASE_NAME-pg-policy`	Single-instance database identity and its secret access	`postgres.enabled: true`

Your keys secret (see Prerequisites) is not created by the template.

Prerequisites

Chatwoot signs its sessions and encrypts sensitive columns with four keys that you supply through a dictionary secret created before installing. The values never pass through Helm values.

Create the keys secret

All four keys are required. Secrets are org-level, so no --gvc flag is involved:

cpln secret create-dictionary --name CHATWOOT_KEYS_SECRET_NAME \
  --entry SECRET_KEY_BASE="$(openssl rand -hex 64)" \
  --entry ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY="$(openssl rand -hex 16)" \
  --entry ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY="$(openssl rand -hex 16)" \
  --entry ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT="$(openssl rand -hex 16)"

Set secrets.name to this name.

Back the four values up

Store a copy outside Control Plane. All four keys are write-once for the life of the installation: rotating SECRET_KEY_BASE logs out every user, and rotating any ACTIVE_RECORD_ENCRYPTION_* key makes stored two-factor secrets undecryptable, locking out every agent who enabled MFA.

Choose the two bundled passwords

The database password (postgres.credentials.password) and the Redis password (redis.auth.password) ship as change-me-… placeholders that the template uses as-is. Pick strong values and pass them at install time — both seed their component on first boot and are not updated by later value edits. The Redis password may contain only letters, digits, - and _.

If the keys secret does not exist at install time, the deployment wedges silently. cpln logs returns zero lines — the container never starts, so it has nothing to log. The one place the reason appears is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-chatwoot --gvc GVC_NAME -o yaml

Note this is get-deployments — plain cpln workload get has no versions field. Creating the secret repairs the deployment on its own after several minutes, or force a redeployment to skip the wait.

Everything else works with the defaults. Three optional features need their own setup first:

Object-storage attachments — an existing bucket plus either a Control Plane cloud account (AWS S3) or a static-key dictionary secret (S3-compatible servers). See Attachment Storage. Required for more than one web replica.
Authenticated SMTP — a dictionary secret holding SMTP_USERNAME and SMTP_PASSWORD. See Email.
Database backups — a bucket and access setup for AWS S3, Google Cloud Storage or an S3-compatible server. See Backing Up.

Installation

Once the keys secret exists, install into your existing GVC with the two bundled passwords set:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/chatwoot \
  --version 1.2.1 --gvc GVC_NAME \
  --set secrets.name=CHATWOOT_KEYS_SECRET_NAME \
  --set postgres.credentials.password='YOUR-STRONG-DB-PASSWORD' \
  --set redis.auth.password='YOUR-STRONG-REDIS-PASSWORD'

To install using another method, follow the instructions for it:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Each subsection shows the shipped defaults for one top-level values area.

Chatwoot Web

chatwoot:
  image: chatwoot/chatwoot:v4.16.2-ce   # Community Edition (MIT core); pin a released tag, never latest
  replicas: 1                 # >1 REQUIRES storage.type s3 or s3-compatible — local attachments are per-replica
  frontendUrl: ""             # public base URL in widget snippets and email links; empty = the canonical endpoint; set WITH https:// for a custom domain
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi            # a Rails process under boot migrations OOMs below this

Both the web and worker workloads run chatwoot.image. Leave chatwoot.frontendUrl empty unless you front Chatwoot with a custom domain; both tiers then advertise the web workload’s public URL in links.

Sidekiq Worker

worker:
  concurrency: 10             # SIDEKIQ_CONCURRENCY; also the worker's Postgres pool size
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi

The worker is a fixed single replica because it also runs the database migrations and the first-run bootstrap. Scale background throughput with worker.concurrency, not replicas. It has no probes, so it reports ready as soon as it is scheduled, even while migrating — read its logs rather than its readiness:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-chatwoot-worker"}' --limit 50 --since 10m

Prerequisite Secret

secrets:
  name: my-chatwoot-secrets   # dictionary secret with the four root-of-trust keys — MUST exist before install

Attachment Storage

storage:
  # local | s3 | s3-compatible   (object storage required for replicas > 1)
  type: local
  local:
    volumeset:
      capacity: 10            # GiB (minimum 10); mounted at /app/storage
  s3:                         # AWS S3 — keyless only (no static keys accepted)
    bucket: my-chatwoot-bucket
    region: us-east-1
    cloudAccountName: my-s3-cloud-account       # Control Plane cloud account
    policyName: my-chatwoot-s3-policy           # your bucket-scoped IAM policy (JSON below)
  s3Compatible:               # SeaweedFS / MinIO / Spaces — static keys
    bucket: my-chatwoot-bucket
    region: us-east-1         # any value; most S3-compatible servers ignore it
    endpoint: http://my-minio-workload:9000     # S3 API address, with scheme and port
    forcePathStyle: true      # true for most S3-compatible servers
    auth:
      secretName: my-chatwoot-s3-keys           # dictionary secret with STORAGE_ACCESS_KEY_ID + STORAGE_SECRET_ACCESS_KEY

Local volume (default)
AWS S3 (keyless)
S3-compatible (MinIO and others)

Attachments are written to a volume set mounted at /app/storage on the web workload and survive restarts, redeploys and upgrades under the same release name.The volume is attached to the web workload only, so the Sidekiq worker cannot read attachments in this mode — attachment emails and ActiveStorage analyze and purge jobs cannot succeed. Local storage also works only with a single web replica. Use object storage for production.

AWS S3 uses a Control Plane cloud account: no access keys exist anywhere, and the Chatwoot identity authenticates through the account at runtime. This is the only supported way to reach AWS S3; static keys are accepted for S3-compatible endpoints only.

Create a bucket

Create an S3 bucket. Set storage.s3.bucket and storage.s3.region to match.

Set up a cloud account

If you do not have one, create a cloud account for your AWS account. Set storage.s3.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET_NAME), then set storage.s3.policyName to the policy’s name:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::YOUR_BUCKET_NAME",
        "arn:aws:s3:::YOUR_BUCKET_NAME/*"
      ]
    }
  ]
}

Switch the storage type

Set storage.type: s3. The template attaches the cloud account and your policy to the Chatwoot identity.

S3-compatible servers use static access keys held in a dictionary secret you create before installing.

Create a bucket

Create the bucket on your server. For the MinIO template deployed in the same GVC, the S3 API address is http://RELEASE_NAME-minio.GVC_NAME.cpln.local:9000.

Set the endpoint

Set storage.type: s3-compatible, storage.s3Compatible.endpoint to the S3 API address including scheme and port, and keep storage.s3Compatible.forcePathStyle: true.

Create the key secret

Create a dictionary secret with the server’s credentials and set storage.s3Compatible.auth.secretName to its name. The Chatwoot identity is granted reveal on exactly this secret.

cpln secret create-dictionary --name STORAGE_KEYS_SECRET_NAME \
  --entry STORAGE_ACCESS_KEY_ID=YOUR_ACCESS_KEY \
  --entry STORAGE_SECRET_ACCESS_KEY=YOUR_SECRET_KEY

Chatwoot serves an attachment by redirecting the browser to the storage endpoint, so storage.s3Compatible.endpoint must be an address your agents’ and visitors’ browsers can reach. An address that resolves only inside the GVC makes attachments appear broken from outside it, even though the upload itself succeeded.

Email

smtp:
  enabled: false
  address: smtp.example.com   # SMTP_ADDRESS (note: not SMTP_HOST)
  port: 587
  domain: ""                  # HELO domain; empty = omitted
  authentication: login       # plain | login | cram_md5; empty = unauthenticated relay
  enableStarttlsAuto: true    # false for a plaintext mail catcher (e.g. Mailpit :1025)
  fromEmail: Chatwoot <no-reply@example.com>    # MAILER_SENDER_EMAIL
  auth:
    secretName: ""            # optional dictionary secret with SMTP_USERNAME + SMTP_PASSWORD; empty = no auth

SMTP is off by default and a default install works without it — the onboarding wizard creates the first account with no email confirmation. For an authenticated relay, create the credentials secret before installing and set smtp.auth.secretName to its name; the Chatwoot identity is granted reveal on exactly that secret:

cpln secret create-dictionary --name SMTP_SECRET_NAME \
  --entry SMTP_USERNAME=YOUR_SMTP_USERNAME \
  --entry SMTP_PASSWORD=YOUR_SMTP_PASSWORD

With SMTP disabled, Chatwoot falls back to sendmail, which is absent from the image, so nothing is delivered: agent invitations, password resets and email-channel replies all fail. Configure smtp.* before inviting agents.

Access

publicAccess:
  enabled: true               # HTTPS UI, API, widget and WebSockets on the auto *.cpln.app endpoint
internalAccess:
  type: same-gvc              # none | same-gvc | same-org | workload-list
  workloads: []               # used only with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

Public access is on by default because the chat widget and your visitors live outside the GVC. Set publicAccess.enabled: false for an internal-only instance; in-GVC callers still reach it according to internalAccess.type:

Type	Description
`none`	No internal access.
`same-gvc`	Allow access from all workloads in the same GVC (default).
`same-org`	Allow access from all workloads in the same org.
`workload-list`	Allow access only from the workloads listed in `internalAccess.workloads`.

The worker and the bundled Redis are never publicly reachable: the worker accepts no inbound traffic, and Redis accepts only same-GVC traffic.

Database

Enable exactly one of postgresHA (default) and postgres — the chart refuses to render with both or neither. Chatwoot is wired to the active database automatically: the HAProxy leader endpoint in HA mode, or the single instance directly. In both modes the database credentials come from postgres.credentials.*: this template writes them into a dictionary secret named by postgresHA.config.credentialsSecretName or postgres.config.credentialsSecretName and hands that name to the bundled database. There is nothing for you to create.

# Highly available PostgreSQL (default): 3 Patroni replicas (PostgreSQL 17.5), 3 etcd replicas,
# an HAProxy leader endpoint. Its image ships pgvector, which Chatwoot's schema REQUIRES.
postgresHA:
  enabled: true
  config:
    credentialsSecretName: my-chatwoot-db-credentials   # secret this chart CREATES from postgres.credentials.*; org-wide name — give each release its own
  replicas: 3
  resources:                  # per Patroni replica; the default install runs 3 of these
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi
  volumeset:
    capacity: 10              # GiB per replica (minimum 10)
  backup:                     # optional database backups — see Backing Up
    enabled: false
    mode: logical             # logical | wal-g
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0   # 17.1.0 matches PostgreSQL 17
      schedule: "0 2 * * *"   # daily at 2am UTC
    walg:
      intervalSeconds: 21600
    provider: aws             # aws | gcp | minio
    aws:
      bucket: my-chatwoot-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: my-chatwoot-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: my-chatwoot-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: my-chatwoot-pg-backup-bucket
      credentialsSecretName: my-chatwoot-minio-credentials   # REQUIRED prerequisite dictionary secret with accessKey + secretKey when provider is minio
      prefix: postgres/backups

# Single-instance PostgreSQL (dev/lightweight): set postgres.enabled: true AND postgresHA.enabled: false.
postgres:
  enabled: false
  image: pgvector/pgvector:pg18   # MUST carry pgvector — the stock postgres:18 image does NOT (render is refused)
  credentials:                # bundled database credentials, used in BOTH modes
    username: chatwoot
    password: change-me-chatwoot-pg   # change before install
    database: chatwoot
  config:
    credentialsSecretName: my-chatwoot-db-credentials   # secret this chart CREATES; org-wide name — give each release its own
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10              # GiB (minimum 10)
  backup:                     # optional database backups — see Backing Up
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0   # 18.1.0 matches PostgreSQL 18
    schedule: "0 2 * * *"     # daily at 2am UTC
    provider: aws             # aws | gcp | minio
    aws:
      bucket: my-chatwoot-pg-backup-bucket
      region: us-east-1
      cloudAccountName: my-s3-cloud-account
      policyName: my-chatwoot-pg-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: my-chatwoot-pg-backup-bucket
      cloudAccountName: my-gcs-cloud-account
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: my-chatwoot-pg-backup-bucket
      credentialsSecretName: my-chatwoot-minio-credentials   # REQUIRED prerequisite dictionary secret with accessKey + secretKey when provider is minio
      prefix: postgres/backups

The other keys of the bundled postgres-highly-available and postgres templates are available under postgresHA.* and postgres.*, with one exception: postgresHA.proxy.enabled must stay true, because the HAProxy endpoint is the address Chatwoot connects to.

Choose the database mode before installing — it cannot be switched later. Flipping postgresHA.enabled / postgres.enabled on a live release points Chatwoot at a different, empty database (a separate volume set and a different PostgreSQL major version), so the app re-runs onboarding and your existing conversations are orphaned rather than migrated.

Secret names are org-wide, and the credentials secret is created by this template in both modes. If you run more than one release of this template in the same org, give each its own postgresHA.config.credentialsSecretName (or postgres.config.credentialsSecretName). A second release left on the default name is refused at install and creates nothing; the first release is unaffected.

Redis

redis:
  image: redis:8
  auth:
    password: change-me-chatwoot-redis   # template-managed; wired into REDIS_URL — letters/digits/-/_ only
  resources:
    minCpu: 100m
    maxCpu: 400m
    minMemory: 256Mi
    maxMemory: 512Mi
  volumeset:
    capacity: 10              # GiB (minimum 10); AOF at /data

Redis is required and runs as a single node by design: it carries the pub/sub channel behind every live update, and Redis does not propagate published messages between replicas, so a multi-node topology would silently drop a share of the updates that make the dashboard and widget refresh in real time. Persistence is on and eviction is disabled, so a queued job is never dropped. Change redis.auth.password before installing; only letters, digits, - and _ are accepted because the value is embedded in a connection URL.

Connecting

What	Address	Notes
Dashboard, API and chat widget	`https://<canonical>.cpln.app`	`status.canonicalEndpoint` of `RELEASE_NAME-chatwoot` — see the command below
WebSocket endpoint	`wss://<canonical>.cpln.app/cable`	Used by the dashboard and the widget; no separate configuration
Health checks	`/api` (readiness — reports PostgreSQL and Redis status) and `/health` (liveness)	Both unauthenticated
Internal (same GVC)	`http://RELEASE_NAME-chatwoot.GVC_NAME.cpln.local:3000`	Subject to `internalAccess.type`
Login	The account created by the onboarding wizard	See First Run
PostgreSQL (HA mode)	`RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local:5432`	Credentials in the secret named by `postgresHA.config.credentialsSecretName`
PostgreSQL (single-instance mode)	`RELEASE_NAME-postgres.GVC_NAME.cpln.local:5432`	Credentials in the secret named by `postgres.config.credentialsSecretName`
Redis	`RELEASE_NAME-chatwoot-redis.GVC_NAME.cpln.local:6379`	Password in the `redisPassword` key of `RELEASE_NAME-chatwoot-creds`

Read the public hostname and the stored credentials:

cpln workload get RELEASE_NAME-chatwoot --gvc GVC_NAME -o yaml      # status.canonicalEndpoint
cpln secret reveal DB_CREDENTIALS_SECRET_NAME -o yaml               # the name you set in *.config.credentialsSecretName
cpln secret reveal RELEASE_NAME-chatwoot-creds -o yaml              # redisPassword

To verify the web tier from your machine without going through the public endpoint, forward port 3000 and query the readiness route, which reports the PostgreSQL and Redis status:

cpln port-forward RELEASE_NAME-chatwoot 3000:3000 --gvc GVC_NAME
curl -s http://localhost:3000/api

First Run

Chatwoot ships no default account. The first browser session to reach the endpoint runs the onboarding wizard, and the user it creates is the super admin.

Wait for the web workload to report ready

On the default HA database path a first install takes several minutes: the database cluster elects a leader, the worker loads the schema and runs the migrations, and only then does the web tier pass its readiness probe. The worker may restart a few times while the database comes up — that is expected on a first HA install.

cpln workload get-deployments RELEASE_NAME-chatwoot --gvc GVC_NAME -o yaml

Complete the onboarding wizard

Browse to the canonical endpoint of RELEASE_NAME-chatwoot. It redirects to /installation/onboarding, where the form creates your account and the super admin user. Do this as soon as the workload is ready — the wizard is unauthenticated until it has been completed. For an install with publicAccess.enabled: false, reach the same page through cpln port-forward RELEASE_NAME-chatwoot 3000:3000 --gvc GVC_NAME at http://localhost:3000.

Create an inbox

In the dashboard, add an inbox — a website widget for live chat, or an API channel for a custom integration. The widget snippet and the API channel identifier are issued there.

Configure email before inviting agents

Agent invitations, password resets and email-channel replies are all delivered by mail. Set up SMTP before you invite your team.

Instance-wide settings live in Chatwoot’s database, not in Helm values. Sign in as the super admin at https://<canonical>.cpln.app/super_admin; under Settings, ENABLE_ACCOUNT_SIGNUP controls whether visitors can create their own accounts. Self-serve signup is off on a fresh install — accounts come from the onboarding wizard and from agent invitations until you turn it on.

Operations

Backing Up

Database backups are optional and off by default. They cover the PostgreSQL database — conversations, contacts, inboxes and users. Attachments are not included: in object-storage mode they live in your bucket, in local mode on the RELEASE_NAME-chatwoot-storage volume set. Enable backups with postgresHA.backup.enabled: true or postgres.backup.enabled: true (matching your database mode) and complete the storage setup for your provider before installing. The keys below are shown as backup.*; set them inside the enabled database block.

AWS S3
Google Cloud Storage
S3-compatible (MinIO and others)

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region to match.

Set up a cloud account

If you do not have one, create a cloud account for your AWS account. Set backup.aws.cloudAccountName to its name.

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET_NAME), then set backup.aws.policyName to the policy’s name:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject",
      "s3:ListBucket",
      "s3:GetObjectVersion",
      "s3:DeleteObjectVersion"
    ],
    "Resource": [
      "arn:aws:s3:::YOUR_BUCKET_NAME",
      "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    ]
  }]
}

Create a bucket

Create a GCS bucket. Set backup.gcp.bucket to its name.

Set up a cloud account

If you do not have one, create a cloud account for your GCP project. Set backup.gcp.cloudAccountName to its name — access is keyless.

Grant bucket access

Grant the Storage Object Admin role (roles/storage.objectAdmin) on that bucket to the GCP service account created for the cloud account.

Create a bucket

Create your bucket on the server. Set backup.minio.bucket to its name.

Set the endpoint

Set backup.minio.endpoint to the S3 API address including scheme and port. For the MinIO template deployed in the same GVC, this is http://RELEASE_NAME-minio.GVC_NAME.cpln.local:9000.

Create the credentials secret

In both database modes the server’s keys are a prerequisite dictionary secret holding exactly accessKey and secretKey. Create it before installing and set backup.minio.credentialsSecretName to its name:

cpln secret create-dictionary --name MINIO_BACKUP_SECRET_NAME \
  --entry accessKey=YOUR_ACCESS_KEY \
  --entry secretKey=YOUR_SECRET_KEY

In HA mode, backup.mode selects logical (a scheduled dump run by the RELEASE_NAME-postgres-ha-backup cron workload) or wal-g (continuous WAL archiving from the database workload). Single-instance mode takes scheduled logical dumps through RELEASE_NAME-postgres-backup. backup.*.prefix is the key prefix within the bucket, and the schedule is a standard cron expression in UTC.

Restoring a Backup

The database restore is the one documented for the bundled database: Restoring a Backup on the postgres-highly-available page (logical and WAL-G), or Restoring a Backup on the postgres page. In HA mode, connect through RELEASE_NAME-postgres-ha-proxy.GVC_NAME.cpln.local so the restore targets the current leader; use the username and password from the secret named by *.config.credentialsSecretName. Two Chatwoot-specific points:

The web and worker workloads must not be writing to the database while a logical dump is replayed. After the restore, force a redeployment of both so they reconnect and the cache is rebuilt:
cpln workload force-redeployment RELEASE_NAME-chatwoot --gvc GVC_NAME cpln workload force-redeployment RELEASE_NAME-chatwoot-worker --gvc GVC_NAME
Attachments are restored separately: copy them back into the bucket (object-storage mode) or onto the RELEASE_NAME-chatwoot-storage volume set (local mode).

This restore path has not been exercised against a Chatwoot install. The database procedure is the bundled template’s own; follow it with a test release first, and keep the four keys from your prerequisite secret with the backup — a dump restored under different ACTIVE_RECORD_ENCRYPTION_* keys cannot decrypt the two-factor secrets it contains.

Upgrading From 1.0.0

Version 1.0.1 only updates the bundled highly available database to a release that compacts its etcd cluster. Without compaction, etcd’s backend grows with time alone and eventually goes read-only, taking PostgreSQL failover with it. Upgrade; see etcd History Compaction for the mechanism and the symptoms. Only installs running the HA database (postgresHA.enabled, the default) are affected. Compaction stops further growth but cannot shrink a backend that has already grown.

Upgrading From 1.0.1 or Earlier

Version 1.1.0 changed the single-instance database path:

postgres.config.username, postgres.config.password and postgres.config.database moved to postgres.credentials.username, postgres.credentials.password and postgres.credentials.database. The new postgres.config.credentialsSecretName names the dictionary secret this template now creates from those three values. Carrying the old keys fails the render with config.username was REMOVED in postgres 3.4.0 — move the three keys and you are done, and ignore that message’s advice to create a secret yourself.
postgres.backup.minio.accessKey and postgres.backup.minio.secretKey were replaced by postgres.backup.minio.credentialsSecretName, a prerequisite dictionary secret holding accessKey and secretKey — see Backing Up.

Keep postgres.credentials.* equal to the values your database was initialised with; the running database still enforces them.

Upgrading From 1.1.0 or Earlier

Version 1.2.0 moved the highly available database to postgres-highly-available 2.5.0, which no longer creates its own credentials secret:

postgresHA.postgres.username, postgresHA.postgres.password and postgresHA.postgres.database were removed. Carrying them fails the render with the postgres block was REMOVED in 2.5.0. Delete the block.
In HA mode the credentials now come from postgres.credentials.* — the same keys the single-instance path uses — and this template writes them into the secret named by the new postgresHA.config.credentialsSecretName.

Use the credentials your cluster already has. Set postgres.credentials.username, postgres.credentials.password and postgres.credentials.database to exactly the values your postgresHA.postgres.* block held. The database was initialised with them and still enforces them; putting new values in the secret does not change the running database — it gives Chatwoot a password that no longer works.

Upgrading From 1.2.0 or Earlier

Version 1.2.1 replaced postgresHA.backup.minio.accessKey and postgresHA.backup.minio.secretKey with postgresHA.backup.minio.credentialsSecretName, a prerequisite dictionary secret holding accessKey and secretKey. Only installs backing up the HA database to an S3-compatible server are affected — see Backing Up for the secret.

Scaling and Availability

Web tier — chatwoot.replicas sets how many web replicas run. Replicas share the database and the bundled Redis, so a message received by one replica reaches a WebSocket client connected to another, and no sticky sessions are needed. Anything above 1 requires storage.type s3 or s3-compatible; the chart refuses to render the combination with local storage.
chatwoot: replicas: 2 storage: type: s3 s3: bucket: my-chatwoot-bucket region: us-east-1 cloudAccountName: my-s3-cloud-account policyName: my-chatwoot-s3-policy
Worker and Redis — both are fixed at one replica. Scale background throughput with worker.concurrency.
Database — the default postgresHA path keeps serving through a replica failure and a rolling restart; the postgres path has no failover and is for development or light use. The mode is an install-time choice.
Helm upgrades — a helm upgrade can restart the bundled datastores even when their values did not change, and the web tier is unready while Redis is down; upgrade in a quiet window.
After any Redis restart, restart the web workload. Background jobs and the cache reconnect on their own, but the web tier’s live-update subscription does not: nothing is logged, the health endpoint stays green, and agents and visitors stop seeing new messages until they refresh. A forced redeployment of the web workload restores it:
cpln workload force-redeployment RELEASE_NAME-chatwoot --gvc GVC_NAME

Troubleshooting

The deployment never starts and cpln logs is empty

Symptom: RELEASE_NAME-chatwoot and RELEASE_NAME-chatwoot-worker never reach ready, and cpln logs returns zero lines.Cause: a secret referenced by name does not exist — usually the keys secret (secrets.name), or the storage or SMTP secret when those features are enabled. The container never starts, so there is nothing to log.Fix: read status.versions[].message, which names the missing secret, then create it. The deployment recovers on its own after several minutes, or force a redeployment to skip the wait.

cpln workload get-deployments RELEASE_NAME-chatwoot --gvc GVC_NAME -o yaml
cpln workload force-redeployment RELEASE_NAME-chatwoot --gvc GVC_NAME

The web workload stays unready and logs waiting for the chatwoot schema

Symptom: the web log repeats waiting for the chatwoot schema... and the readiness probe never passes.Cause: the web tier deliberately stays down until the worker has created the schema, so this means the worker’s migration has not completed. On a first HA install the worker restarts a few times with PG::ConnectionBad while the database cluster elects a leader, which is expected. A migration that keeps failing is not.Fix: read the worker’s log — the worker reports ready even while crash-looping, so its readiness is not a signal.

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-chatwoot-worker"} |= "ERROR"' --limit 50 --since 10m

Live updates stopped after a Redis restart

Symptom: new messages appear only after a page refresh; /api still reports healthy and nothing is logged.Cause: the bundled Redis restarted (a redeploy, a reschedule or a Helm upgrade) and the web tier’s live-update subscription did not re-establish.Fix: force a redeployment of the web workload.

cpln workload force-redeployment RELEASE_NAME-chatwoot --gvc GVC_NAME

Render fails with config.username was REMOVED in postgres 3.4.0

Symptom: helm upgrade fails before anything is applied, citing config.username was REMOVED in postgres 3.4.0.Cause: your values still carry the 1.0.x single-instance keys postgres.config.username, postgres.config.password or postgres.config.database.Fix: move the three keys to postgres.credentials.* as described in Upgrading From 1.0.1 or Earlier. Do not create a secret yourself — this template creates it.

Render fails with the postgres block was REMOVED in 2.5.0

Symptom: helm upgrade fails before anything is applied, citing the postgres block was REMOVED in 2.5.0.Cause: your values still carry postgresHA.postgres.username, postgresHA.postgres.password or postgresHA.postgres.database from version 1.1.0 or earlier.Fix: delete the postgresHA.postgres block and put the same three values under postgres.credentials.* — see Upgrading From 1.1.0 or Earlier.

A second release is refused at install as managed by a different release

Symptom: installing a second Chatwoot release in the same org fails with cannot be updated because it is being managed by a different release, and nothing is created.Cause: both releases use the same credentialsSecretName. Secret names are org-wide, and the first release owns that secret.Fix: give the second release its own postgresHA.config.credentialsSecretName (or postgres.config.credentialsSecretName). The first release is unaffected.

Attachments upload but appear broken in the browser

Symptom: with storage.type: s3-compatible, uploads succeed but images and files fail to load for agents or visitors.Cause: Chatwoot serves an attachment by redirecting the browser to storage.s3Compatible.endpoint, and that address resolves only inside the GVC.Fix: point storage.s3Compatible.endpoint at an address your users’ browsers can reach, and run helm upgrade.

Agent invitations and password-reset emails never arrive

Symptom: invitations, password resets and email-channel replies are not delivered.Cause: smtp.enabled is false. Chatwoot then falls back to sendmail, which the image does not contain.Fix: configure smtp.* as described in Email and run helm upgrade.

Render fails because replicas above 1 require object storage

Symptom: helm install or helm upgrade fails with chatwoot.replicas > 1 requires storage.type 's3' or 's3-compatible'.Cause: local attachments live on a volume set attached to one web replica, so a file uploaded through one replica would be missing from another.Fix: switch to object storage as described in Attachment Storage before raising chatwoot.replicas.

Important Notes

Create the keys secret before installing — secrets.name must name an existing dictionary secret holding SECRET_KEY_BASE and the three ACTIVE_RECORD_ENCRYPTION_* keys; a missing secret wedges the deployment silently.
All four keys are write-once — rotating SECRET_KEY_BASE logs out every user, and rotating an ACTIVE_RECORD_ENCRYPTION_* key makes stored two-factor secrets undecryptable. Back the values up outside Control Plane.
Set postgres.credentials.password and redis.auth.password at install time — both ship as placeholders, seed their component on first boot, and are not updated by later value edits.
Complete the onboarding wizard right after install — the first browser session to reach the endpoint creates the super admin, with no email confirmation.
Restart the web workload after any Redis restart — live updates stop silently until it restarts.
Choose the database mode before installing — switching postgresHA and postgres on a live release points Chatwoot at a different, empty database.
In single-instance mode the database image must carry pgvector — keep postgres.image on a pgvector build; the chart refuses a stock postgres: image.
chatwoot.replicas above 1 requires object storage — local attachments are per-replica.
In local storage mode the worker cannot read attachments — attachment emails and ActiveStorage analyze and purge jobs fail. Use object storage for production.
AWS S3 is keyless only — a cloud account plus a bucket-scoped IAM policy; static keys are accepted only for S3-compatible endpoints.
With SMTP off, no mail is delivered — configure smtp.* before inviting agents.
Do not scale the worker or Redis — both are fixed singletons; scale background throughput with worker.concurrency.
Give each release its own credentialsSecretName — secret names are org-wide and a second release on the default name is refused at install.
Self-serve signup is managed in the app — turn it on at /super_admin under Settings; it is off on a fresh install.
Enterprise features are not included — the -ce image omits SSO/SAML, audit logs, agent capacity management, custom branding, SLA policies and Captain AI.
Data survives restarts and upgrades — conversations live in the database volume sets and local attachments in RELEASE_NAME-chatwoot-storage. Uninstalling deletes those volume sets; your keys secret survives an uninstall.

External References

Chatwoot Self-Hosted Docs

Official self-hosting documentation

Environment Variables

Every setting the Chatwoot application reads from its environment

Super Admin Console

Instance settings and the Sidekiq dashboard at /super_admin

Community vs Enterprise

What the Community Edition image includes and excludes

Chatwoot on GitHub

Source code and release notes

Chatwoot Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Chatwoot Web

Sidekiq Worker

Prerequisite Secret

Attachment Storage

Email

Access

Database

Redis

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading From 1.0.0

Upgrading From 1.0.1 or Earlier

Upgrading From 1.1.0 or Earlier

Upgrading From 1.2.0 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References

Chatwoot Self-Hosted Docs

Environment Variables

Super Admin Console

Community vs Enterprise

Chatwoot on GitHub

Chatwoot Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Chatwoot Web

​Sidekiq Worker

​Prerequisite Secret

​Attachment Storage

​Email

​Access

​Database

​Redis

​Connecting

​First Run

​Operations

​Backing Up

​Restoring a Backup

​Upgrading From 1.0.0

​Upgrading From 1.0.1 or Earlier

​Upgrading From 1.1.0 or Earlier

​Upgrading From 1.2.0 or Earlier

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Chatwoot Self-Hosted Docs

Environment Variables

Super Admin Console

Community vs Enterprise

Chatwoot on GitHub

Chatwoot Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Chatwoot Web

Sidekiq Worker

Prerequisite Secret

Attachment Storage

Email

Access

Database

Redis

Connecting

First Run

Operations

Backing Up

Restoring a Backup

Upgrading From 1.0.0

Upgrading From 1.0.1 or Earlier

Upgrading From 1.1.0 or Earlier

Upgrading From 1.2.0 or Earlier

Scaling and Availability

Troubleshooting

Important Notes

External References