Chatwoot

Overview

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

Architecture

Chatwoot web — A stateful workload running the official image, serving the agent dashboard, the REST and public APIs, the chat widget, and the ActionCable WebSocket endpoint on port 3000. Scale it with chatwoot.replicas.
Chatwoot worker — A standard workload running Sidekiq from the same image. It also runs the database migrations and the first-run bootstrap on boot, so it is a fixed single replica; background throughput scales through worker.concurrency instead.
PostgreSQL (HA, default) — The postgres-highly-available template as a subchart: 3× Patroni PostgreSQL 17.5, 3× etcd, and a HAProxy leader endpoint Chatwoot connects through. Its image ships pgvector, which Chatwoot’s schema requires.
PostgreSQL (dev/lightweight, optional) — The single-instance postgres template instead, on a pgvector image.
Redis — A bundled single-node stateful workload with AOF persistence and password authentication, carrying the Sidekiq queues, the ActionCable pub/sub channel that drives every live update, the cache, and the one-time install-onboarding flag.

What Gets Created

Stateful Chatwoot Web Workload — {release}-chatwoot on port 3000, at chatwoot.replicas replicas, with /api as its readiness probe and /health as its liveness probe.
Standard Chatwoot Worker Workload — {release}-chatwoot-worker, a fixed single replica running Sidekiq, migrations, and the first-run bootstrap. It has no inbound access and no ports.
Stateful Redis Workload — {release}-chatwoot-redis on port 6379, pinned to one node, reachable only from inside the GVC.
Database Workloads — HA mode: a stateful Patroni PostgreSQL workload, a stateful etcd workload, and a HAProxy leader-routing workload. Single-instance mode: one stateful PostgreSQL workload.
Volume Sets — {release}-chatwoot-redis-vs for the Redis AOF file at /data, {release}-chatwoot-storage for local attachments at /app/storage (only when storage.type is local), plus the database subchart’s volumes.
Secrets — A template-created dictionary secret ({release}-chatwoot-creds) holding the bundled Redis password, two opaque start-script secrets for the web and worker containers, and the database credentials from the subchart. Your prerequisite keys secret is not created by the template — see Prerequisites.
Identity & Policy — One identity shared by the web and worker workloads, and a policy granting it reveal on exactly the secrets those workloads read: the database credentials, the two start scripts, the Redis credentials secret, your prerequisite secret, and — when configured — the S3 key and SMTP secrets. In keyless S3 mode the identity also carries the cloud account link and your bucket-scoped IAM policy.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

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

Create the keys secret

All four keys are required. Generate them with openssl:

cpln secret create-dictionary --name my-chatwoot-secrets \
  --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 the secret’s name (default my-chatwoot-secrets). Secrets are org-level, so no GVC flag is involved.

Back the values up

Store a copy somewhere safe, outside Control Plane. All four keys are write-once for the life of the installation.

Change the bundled credentials

Change the database password (postgresHA.postgres.password or postgres.config.password) and the Redis password (redis.auth.password) from their placeholder defaults before installing. Both seed their component on first boot and are not updated by later value edits.

Create the keys secret before installing — the workloads reference it by name, and a missing secret pauses the deployment indefinitely, which looks like a broken install. The keys are also write-once: 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.

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 secret (S3-compatible servers). See Attachment Storage. Required if you plan to run 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 one of the supported providers. See Backing Up.

Once your keys secret exists, install the template using your preferred method:

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

First Run

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

Wait for the web workload to report ready

On the default HA database path a first install takes roughly eight minutes end to end: the Patroni cluster elects a leader, the worker then loads the schema and runs 158 migrations, and only then does the web tier pass its readiness probe. The single-instance database path is closer to three and a half minutes.

Complete the onboarding wizard

Browse to the canonical *.cpln.app endpoint of the {release}-chatwoot workload. 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 is completed.

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.

Once an inbox exists, incoming visitor messages and agent replies travel over the WebSocket connection: an agent sees a new message without refreshing, and the widget receives the agent’s reply live.

Configuration

The default values.yaml for this template:

chatwoot:
  image: chatwoot/chatwoot:v4.16.2-ce # Community Edition (MIT core); pin a released tag
  replicas: 1 # >1 REQUIRES storage.type s3 or s3-compatible
  frontendUrl: "" # public base URL used in links; empty = derive from the canonical endpoint
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi # a Rails process under boot migrations OOMs below this

worker: # Sidekiq; single replica — it also runs migrations and the first-run bootstrap
  concurrency: 10 # SIDEKIQ_CONCURRENCY; also the worker's Postgres pool size
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 2Gi

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

storage:
  type: local # local | s3 | s3-compatible (object storage required for replicas > 1)
  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
  s3Compatible: # MinIO / SeaweedFS / 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

smtp:
  enabled: false # off = agent invites, password resets and email replies FAIL
  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
  fromEmail: Chatwoot <no-reply@example.com> # MAILER_SENDER_EMAIL
  auth:
    secretName: "" # optional dictionary secret with SMTP_USERNAME + SMTP_PASSWORD

publicAccess:
  enabled: true # HTTPS UI, API, widget and WebSockets on the auto *.cpln.app endpoint

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

postgresHA: # default: highly available PostgreSQL 17.5, pgvector native
  enabled: true
  postgres:
    username: chatwoot
    password: change-me-chatwoot-pg # change before installing
    database: chatwoot
  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:
    enabled: false # optional — see Backing Up
    mode: logical # logical | wal-g
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      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
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

postgres: # dev/lightweight: single-instance PostgreSQL (disable postgresHA first)
  enabled: false
  image: pgvector/pgvector:pg18 # MUST carry pgvector — stock postgres:18 does not
  config:
    username: chatwoot
    password: change-me-chatwoot-pg # change before installing
    database: chatwoot
  resources:
    minCpu: 250m
    maxCpu: 1000m
    minMemory: 512Mi
    maxMemory: 1Gi
  volumeset:
    capacity: 10 # GiB (minimum 10)
  backup:
    enabled: false # optional — see Backing Up
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    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
      accessKey: my-minio-username
      secretKey: my-minio-password
      prefix: postgres/backups

redis: # bundled single node — queues, live updates, cache (required)
  image: redis:8
  auth:
    password: change-me-chatwoot-redis # letters/digits/-/_ only; change before installing
  resources:
    minCpu: 100m
    maxCpu: 400m
    minMemory: 256Mi
    maxMemory: 512Mi
  volumeset:
    capacity: 10 # GiB (minimum 10); AOF at /data

Chatwoot Web

chatwoot.image — The Community Edition image, used by both the web and worker workloads. Pin a released -ce tag.
chatwoot.replicas — Web-tier replica count. Anything above 1 requires object storage; see Scaling.
chatwoot.frontendUrl — The public base URL Chatwoot puts in the widget snippet, email links, and callbacks, including the https:// scheme. Leave it empty to derive it from the web workload’s canonical endpoint; set it when you serve Chatwoot on a custom domain. The worker advertises the same URL, so mailer links always point at the web tier.
chatwoot.resources — CPU and memory bounds for the web container. The memory ceiling leaves headroom for the Rails boot path.

Sidekiq Worker

worker.concurrency — Number of background jobs Sidekiq processes in parallel. It also sets this process’s PostgreSQL connection-pool size.
worker.resources — CPU and memory bounds for the worker container.

The worker is a fixed single replica: it runs the database migrations and the first-run bootstrap, which are not safe to run concurrently on a fresh database. Scale background throughput with worker.concurrency instead.

The worker workload has no probes — Sidekiq exposes no port, and its failure mode is process exit, which restarts the container. It therefore reports ready as soon as it is scheduled, even while it is still migrating. Worker readiness is not a health signal; read its logs instead.

Attachment Storage

storage.type decides where uploaded files and images are kept.

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

Attachments are written to a persistent volume set mounted at /app/storage on the web workload, and survive restarts, redeploys, and upgrades under the same release name.

storage:
  type: local
  local:
    volumeset:
      capacity: 10 # GiB (minimum 10)

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 replica. Use object storage for production.

AWS S3 uses a Control Plane cloud identity: no credentials are stored anywhere, and the workload’s identity vends temporary credentials at runtime. This is the only supported way to reach AWS S3 — the chart accepts static keys 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 with your bucket), 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, and no access keys exist anywhere.

S3-compatible servers cannot federate with a cloud account, so they use static access keys held in a dictionary secret.

Create a bucket

Create the bucket on your server. For the MinIO template deployed in the same GVC, the S3 API address is http://WORKLOAD_NAME.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 (required by most S3-compatible servers).

Create the key secret

Create a dictionary secret with the server’s credentials before installing, and set storage.s3Compatible.auth.secretName to its name:

cpln secret create-dictionary --name my-chatwoot-s3-keys \
  --entry STORAGE_ACCESS_KEY_ID=YOUR_ACCESS_KEY \
  --entry STORAGE_SECRET_ACCESS_KEY=YOUR_SECRET_KEY

The Chatwoot identity is granted reveal on exactly this secret.

Chatwoot serves an attachment by redirecting the browser to the storage endpoint. storage.s3Compatible.endpoint must therefore be an address your agents’ and visitors’ browsers can reach — an in-GVC-only address such as http://my-minio.my-gvc.cpln.local:9000 makes attachments appear broken outside the GVC, even though the upload itself succeeded.

Scaling

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.

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

chatwoot.replicas above 1 requires storage.type s3 or s3-compatible. Local attachments live on a per-replica volume, so a file uploaded through one replica would 404 from another. The chart refuses to render the combination.

At two replicas, forcing a redeployment of the web workload served every request without a single HTTP error, and a live agent reply still reached the visitor’s socket while both replicas were serving.

Email

SMTP is off by default, and a default install works without it — the onboarding wizard creates the super admin with no email confirmation, and that account signs in with its password.

smtp:
  enabled: true
  address: smtp.example.com
  port: 587
  domain: example.com
  authentication: login
  enableStarttlsAuto: true
  fromEmail: Chatwoot <no-reply@example.com>
  auth:
    secretName: my-chatwoot-smtp # dictionary secret with SMTP_USERNAME + SMTP_PASSWORD

smtp.address — The relay hostname. Chatwoot reads SMTP_ADDRESS, not SMTP_HOST.
smtp.domain — The HELO domain. Empty omits it.
smtp.authentication — plain, login, or cram_md5. Leave it empty for an unauthenticated relay.
smtp.enableStarttlsAuto — Set false only for a plaintext relay such as a local mail catcher.
smtp.fromEmail — The From address on outbound mail.
smtp.auth.secretName — Optional dictionary secret with the relay credentials, created before installing:

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

Leave it empty for a relay that needs no authentication. When it is set, the Chatwoot identity is granted reveal on exactly that secret.

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 — Serve the dashboard, API, widget, and WebSockets on the auto-assigned *.cpln.app HTTPS endpoint (default). Because the widget and visitors live outside the GVC, public access is on by default. Set to false for an internal-only instance: external requests are refused at the edge, and in-GVC callers still reach it per internalAccess.
internalAccess.type — Controls which workloads can reach the Chatwoot web tier over the internal network:

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 organization.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`.

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

Database

Enable exactly one of postgresHA (default) or postgres — the chart refuses to render with both or neither enabled. Chatwoot is wired to the active database automatically: the HAProxy leader endpoint in HA mode, or the single instance directly.

postgresHA (default) — 3× Patroni PostgreSQL 17.5 with etcd and a HAProxy leader endpoint. Its image ships pgvector natively, which is why it is the default. A first install on this path takes roughly eight minutes.
postgres — One PostgreSQL instance for lighter, non-production deployments. It reaches ready in a few minutes but has no failover.

In both modes, change the database password before installing (postgresHA.postgres.password / postgres.config.password) — it seeds the database on first boot and is not updated by later value edits.

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.

In single-instance mode, postgres.image must carry pgvector. Chatwoot’s schema runs CREATE EXTENSION "vector", which the stock postgres: image does not provide. The chart refuses to render against a stock postgres: image rather than letting the install fail later as a cryptic schema error — keep the default pgvector/pgvector:pg18 unless you supply your own pgvector build.

On the HA path the worker crash-loops a handful of times during the first install, logging PG::ConnectionBad … server closed the connection unexpectedly while Patroni elects a leader. This is expected and self-heals as soon as the leader accepts writes.

Redis

redis.image — The bundled Redis image.
redis.auth.password — Password for the bundled Redis, embedded in Chatwoot’s REDIS_URL. Change it before installing. Only letters, digits, -, and _ are accepted; other characters would corrupt the connection URL, and the chart rejects them.
redis.resources — CPU and memory bounds for the Redis container.
redis.volumeset.capacity — Volume size in GiB for the append-only file at /data. Persistence is on and eviction is disabled, so a queued job is never silently dropped.

Redis is required and runs as a single node by design, not as a simplification: 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 broadcasts that make the dashboard and widget update in real time. That single node has two operational consequences worth planning for.

Restart the web workload after any Redis restart. If the bundled Redis restarts — a redeploy, a reschedule, or an upgrade — the queues and the cache reconnect on their own, but the web tier’s real-time subscriber does not. Live updates then stop silently: nothing is logged, the health endpoint stays green, and agents and visitors simply stop seeing new messages until they refresh. Force a redeployment of the {release}-chatwoot workload to restore it, which takes about three to four minutes.

cpln workload force-redeployment {release}-chatwoot --gvc GVC_NAME

Expect a few minutes of 503s during a Helm upgrade. An upgrade restarts the bundled Redis, and the web readiness endpoint reports unhealthy without Redis, so every web replica leaves the load balancer until Redis is back — measured at roughly 32% failed requests across a three-minute window, even at two replicas. Upgrade during a quiet period. A redeployment of the web workload alone does not restart Redis and rolls cleanly.

Connecting

What	Value
Public UI, API, and widget	`https://<canonical>.cpln.app` — `status.canonicalEndpoint` of `{release}-chatwoot` (`cpln workload get {release}-chatwoot -o yaml`)
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}-chatwoot.{gvc}.cpln.local:3000`
Login	The super admin account created by the onboarding wizard
PostgreSQL (internal, HA mode)	`{release}-postgres-ha-proxy.{gvc}.cpln.local:5432`, credentials in the `{release}-postgres-config` secret
PostgreSQL (internal, single mode)	`{release}-postgres.{gvc}.cpln.local:5432`, credentials from `postgres.config`
Redis (internal)	`{release}-chatwoot-redis.{gvc}.cpln.local:6379`, password from `redis.auth.password`

Managing the Installation

Chatwoot keeps instance-wide settings in its database rather than in environment variables, so they are managed in the application after install, not through Helm values. Sign in as the super admin and open https://<canonical>.cpln.app/super_admin. Under Settings you can change instance configuration, including ENABLE_ACCOUNT_SIGNUP, which controls whether visitors can create their own accounts. Self-serve signup is off on a fresh install — accounts are created by the onboarding wizard and by agent invitations until you turn it on.

Backing Up

Database backups are optional and disabled by default. They cover the PostgreSQL database — the conversations, contacts, inboxes, and users that make up your Chatwoot instance. Attachments are not included; in object-storage mode they live in your bucket, and in local mode on the attachment volume set. Enable backups with postgresHA.backup.enabled or postgres.backup.enabled (matching your database mode), and complete the storage setup for your provider before installing. The values below are shown under backup.* — set them within 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), 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",
      "arn:aws:s3:::YOUR_BUCKET/*"
    ]
  }]
}

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 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://WORKLOAD_NAME.GVC_NAME.cpln.local:9000.

Set credentials

Set backup.minio.accessKey and backup.minio.secretKey to credentials with access to the bucket.

In HA mode, backup.mode selects logical (a scheduled pg_dump run by a cron workload) or wal-g (continuous WAL archiving). The single-instance mode takes scheduled logical dumps. backup.prefix is the key prefix within the bucket, and backup.*.schedule is a standard cron expression in UTC.

Important Notes

Create the keys secret before installing — secrets.name must point at an existing dictionary secret holding SECRET_KEY_BASE and the three ACTIVE_RECORD_ENCRYPTION_* keys. A missing secret pauses the deployment and the install looks broken until it exists.
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.
Complete the onboarding wizard right after install — the first browser session to reach the endpoint creates the super admin account, with no email confirmation.
Restart the web workload after any Redis restart — queues and cache recover on their own, but live updates stay dead, silently, until the web tier restarts.
A Helm upgrade restarts the bundled Redis and costs a few minutes of 503s — the web readiness probe fails while Redis is down, so replicas leave the load balancer. Upgrade during a quiet period.
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 to render against a stock postgres: image.
chatwoot.replicas above 1 requires object storage — local attachments are per-replica and would 404 across replicas.
In local storage mode the worker cannot read attachments — the volume is attached to the web workload only, so 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 — agent invites, password resets, and email-channel replies all fail. Configure smtp.* before inviting agents.
Do not scale the worker — it is a fixed singleton that also runs migrations and the first-run bootstrap. Scale background throughput with worker.concurrency.
Self-serve signup is managed in the app, not in values — turn it on at /super_admin → Settings; it is off on a fresh install.
Enterprise features are not included — the -ce image omits SSO/SAML and SCIM, audit logs, agent capacity management, custom branding, SLA policies, and Captain AI. The core is MIT-licensed.
Data survives restarts and upgrades — conversations live in the database volume sets and local attachments in the storage volume set. Uninstalling deletes those volume sets and everything in them; your keys secret is yours and survives an uninstall.

External References

Chatwoot Self-Hosted Docs

Official self-hosting documentation

Environment Variables

Every setting the Chatwoot application reads from its environment

Community vs Enterprise

What the Community Edition image includes and excludes

Product Guides

Inboxes, channels, agents, and day-to-day usage

Chatwoot on GitHub

Source code and release notes

Chatwoot Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

Architecture

What Gets Created

Prerequisites

UI

CLI

Terraform

Pulumi

First Run

Configuration

Chatwoot Web

Sidekiq Worker

Attachment Storage

Scaling

Email

Access

Database

Redis

Connecting

Managing the Installation

Backing Up

Important Notes

External References

Chatwoot Self-Hosted Docs

Environment Variables

Community vs Enterprise

Product Guides

Chatwoot on GitHub

Chatwoot Template

​Overview

​Architecture

​What Gets Created

​Prerequisites

UI

CLI

Terraform

Pulumi

​First Run

​Configuration

​Chatwoot Web

​Sidekiq Worker

​Attachment Storage

​Scaling

​Email

​Access

​Database

​Redis

​Connecting

​Managing the Installation

​Backing Up

​Important Notes

​External References

Chatwoot Self-Hosted Docs

Environment Variables

Community vs Enterprise

Product Guides

Chatwoot on GitHub

Chatwoot Template

Overview

Architecture

What Gets Created

Prerequisites

First Run

Configuration

Chatwoot Web

Sidekiq Worker

Attachment Storage

Scaling

Email

Access

Database

Redis

Connecting

Managing the Installation

Backing Up

Important Notes

External References