Deploy Chatwoot on Kubernetes using Helm Charts

This guide will help you to deploy a production ready Chatwoot instance with Helm Charts. To quickly try out the charts, follow the two steps below. For a production deployment, please make sure to pass in the required arguments to helm using your custom values.yaml file.

helm repo add chatwoot https://chatwoot.github.io/charts
helm install chatwoot chatwoot/chatwoot

Prerequisites

Kubernetes 1.16+
Helm 3.1.0+
PV provisioner support in the underlying infrastructure

The helm installation will create 3 “Persistent Volume Claims” for redis, rails and postgres. Setup up a default “Storage Class” (for automatic PV) or create 3 “Persistent Volumes” with the size of 8GB, before installing chatwoot. If the “Persistent Volume Claims” do not claim the “Persistent Volumes”, leave storageClassName blank (inside the PV .yaml files).

Installing the chart

To install the chart with the release name chatwoot, use the following. To deploy it in chatwoot namespace, pass -n chatwoot to the command.

helm install chatwoot chatwoot/chatwoot -f <your-custom-values.yaml> #-n chatwoot

The command deploys Chatwoot on the Kubernetes cluster in the default configuration. The parameters section lists the parameters that can be configured during installation.

List all releases using helm list

Uninstalling the chart

To uninstall/delete the chatwoot deployment:

helm delete chatwoot

The command removes all the Kubernetes components associated with the chart and deletes the release.

Persistent volumes are not deleted automatically. They need to be removed manually.

Parameters

Chatwoot Image parameters

Name	Description	Value
`image.repository`	Chatwoot image repository	`chatwoot/chatwoot`
`image.tag`	Chatwoot image tag (immutable tags are recommended)	`v2.16.0`
`image.pullPolicy`	Chatwoot image pull policy	`IfNotPresent`

Chatwoot Environment Variables

Name	Type	Default Value
`env.ACTIVE_STORAGE_SERVICE`	Storage service. `local` for disk. `amazon` for s3.	`"local"`
`env.ASSET_CDN_HOST`	Set if CDN is used for asset delivery.	`""`
`env.INSTALLATION_ENV`	Sets chatwoot installation method.	`"helm"`
`env.ENABLE_ACCOUNT_SIGNUP`	`true` : allows sign ups, `false` : (default option) disables all the end points related to sign ups, `api_only`: disables the UI for signup but you can create sign ups via the account apis.	`"false"`
`env.FORCE_SSL`	Force all access to the app over SSL, default is set to false.	`"false"`
`env.FRONTEND_URL`	Replace with the URL you are planning to use for your app.	`"http://0.0.0.0:3000/"`
`env.IOS_APP_ID`	Change this variable only if you are using a custom build for mobile app.	`"6C953F3RX2.com.chatwoot.app"`
`env.ANDROID_BUNDLE_ID`	Change this variable only if you are using a custom build for mobile app.	`"com.chatwoot.app"`
`env.ANDROID_SHA256_CERT_FINGERPRINT`	Change this variable only if you are using a custom build for mobile app.	`"AC:73:8E:DE:EB:5............"`
`env.MAILER_SENDER_EMAIL`	The email from which all outgoing emails are sent.	`""`
`env.RAILS_ENV`	Sets rails environment.	`"production"`
`env.RAILS_MAX_THREADS`	Number of threads each worker will use.	`"5"`
`env.SECRET_KEY_BASE`	Used to verify the integrity of signed cookies. Ensure a secure value is set.	`replace_with_your_super_duper_secret_key_base`
`env.SENTRY_DSN`	Sentry data source name.	`""`
`env.SMTP_ADDRESS`	Set your smtp address.	`""`
`env.SMTP_AUTHENTICATION`	Allowed values: `plain`,`login`,`cram_md5`	`"plain"`
`env.SMTP_ENABLE_STARTTLS_AUTO`	Defaults to true.	`"true"`
`env.SMTP_OPENSSL_VERIFY_MODE`	Can be: `none`, `peer`, `client_once`, `fail_if_no_peer_cert`	`"none"`
`env.SMTP_PASSWORD`	SMTP password	`""`
`env.SMTP_PORT`	SMTP port	`"587"`
`env.SMTP_USERNAME`	SMTP username	`""`
`env.USE_INBOX_AVATAR_FOR_BOT`	Bot customizations	`"true"`

Email setup for conversation continuity (Incoming emails)

Name	Type	Default Value
`env.MAILER_INBOUND_EMAIL_DOMAIN`	This is the domain set for the reply emails when conversation continuity is enabled.	`""`
`env.RAILS_INBOUND_EMAIL_SERVICE`	Set this to appropriate ingress channel with regards to incoming emails. Possible values are `relay`, `mailgun`, `mandrill`, `postmark` and `sendgrid`.	`""`
`env.RAILS_INBOUND_EMAIL_PASSWORD`	Password for the email service.	`""`
`env.MAILGUN_INGRESS_SIGNING_KEY`	Set if using mailgun for incoming conversations.	`""`
`env.MANDRILL_INGRESS_API_KEY`	Set if using mandrill for incoming conversations.	`""`

Postgres variables

Name	Type	Default Value
`postgresql.enabled`	Set to `false` if using external postgres and modify the below variables.	`true`
`postgresql.auth.database`	Chatwoot database name	`chatwoot_production`
`postgresql.postgresqlHost`	Postgres host. Edit if using external postgres.	`""`
`postgresql.auth.postgresPassword`	Postgres password. Edit if using external postgres.	`postgres`
`postgresql.postgresqlPort`	Postgres port	`5432`
`postgresql.auth.username`	Postgres username.	`postgres`

Redis variables

Name	Type	Default Value
`redis.auth.password`	Password used for internal redis cluster	`redis`
`redis.enabled`	Set to `false` if using external redis and modify the below variables.	`true`
`redis.host`	Redis host name	`""`
`redis.port`	Redis port	`""`
`redis.password`	Redis password	`""`
`env.REDIS_TLS`	Set to `true` if TLS(`rediss://`) is required	`false`
`env.REDIS_SENTINELS`	Redis Sentinel can be used by passing list of sentinel host and ports.	`""`
`env.REDIS_SENTINEL_MASTER_NAME`	Redis sentinel master name is required when using sentinel.	`""`

Logging variables

Name	Type	Default Value
`env.RAILS_LOG_TO_STDOUT`	string	`"true"`
`env.LOG_LEVEL`	string	`"info"`
`env.LOG_SIZE`	string	`"500"`

Third party credentials

Name	Type	Default Value
`env.S3_BUCKET_NAME`	S3 bucket name	`""`
`env.AWS_ACCESS_KEY_ID`	Amazon access key ID	`""`
`env.AWS_REGION`	Amazon region	`""`
`env.AWS_SECRET_ACCESS_KEY`	Amazon secret key ID	`""`
`env.FB_APP_ID`	For facebook channel, see Facebook setup	`""`
`env.FB_APP_SECRET`	For facebook channel	`""`
`env.FB_VERIFY_TOKEN`	For facebook channel	`""`
`env.SLACK_CLIENT_ID`	For slack integration	`""`
`env.SLACK_CLIENT_SECRET`	For slack integration	`""`
`env.TWITTER_APP_ID`	For twitter channel	`""`
`env.TWITTER_CONSUMER_KEY`	For twitter channel	`""`
`env.TWITTER_CONSUMER_SECRET`	For twitter channel	`""`
`env.TWITTER_ENVIRONMENT`	For twitter channel	`""`

Autoscaling

Name	Type	Default Value
`web.hpa.enabled`	Horizontal Pod Autoscaling for Chatwoot web	`false`
`web.hpa.cputhreshold`	CPU threshold for Chatwoot web	`80`
`web.hpa.minpods`	Minimum number of pods for Chatwoot web	`1`
`web.hpa.maxpods`	Maximum number of pods for Chatwoot web	`10`
`web.replicaCount`	No of web pods if hpa is not enabled	`1`
`worker.hpa.enabled`	Horizontal Pod Autoscaling for Chatwoot worker	`false`
`worker.hpa.cputhreshold`	CPU threshold for Chatwoot worker	`80`
`worker.hpa.minpods`	Minimum number of pods for Chatwoot worker	`2`
`worker.hpa.maxpods`	Maximum number of pods for Chatwoot worker	`10`
`worker.replicaCount`	No of worker pods if hpa is not enabled	`1`

Install with custom parameters

Specify each parameter using the --set key=value[,key=value] argument to helm install. For example,

helm install my-release \
  --set env.FRONTEND_URL="chat.yourdomain.com"\
    chatwoot/chatwoot

The above command sets the Chatwoot server frontend URL to chat.yourdoamain.com. Alternatively, a YAML file that specifies the values for the parameters can be provided while installing the chart. For example,

helm install my-release -f values.yaml chatwoot/chatwoot

You can use the default values.yaml file.

Postgres

PostgreSQL is installed along with the chart if you choose the default setup. To use an external Postgres DB, please set postgresql.enabled to false and set the variables under the Postgres section above.

Redis

Redis is installed along with the chart if you choose the default setup. To use an external Redis DB, please set redis.enabled to false and set the variables under the Redis section above.

Autoscaling

To enable horizontal pod autoscaling, set web.hpa.enabled and worker.hpa.enabled to true. Also make sure to uncomment the values under, resources.limits and resources.requests. This assumes your k8s cluster is already having a metrics-server. If not, deploy metrics-server with the following command.

kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

Upgrading

Do helm repo update and check the version of charts that is going to be installed. Helm charts follows semantic versioning and so if the MAJOR version is different from your installed version, there might be breaking changes. Please refer to the changelog before upgrading.

# update helm repositories
helm repo update
# list your current installed version
helm list
# show the latest version of charts that is going to be installed
helm search repo chatwoot

#if it is major version update, refer to the changelog before proceeding
helm upgrade chatwoot chatwoot/chatwoot -f <your-custom-values>.yaml

Troubleshooting

pod has unbound immediate PersistentVolumeClaims

Make sure the “Persistent Volume Claims” can be satisfied. Refer to prerequisites.

ActionController::InvalidAuthenticityToken HTTP Origin header

ActionController::InvalidAuthenticityToken HTTP Origin header (https://mydomain.com) didn't match request.base_url (http://mydomain.com)

If you are recieving the above error when trying to access the superadmin panel, configure your ingress controller to forward the protocol of the origin request. For nginx ingress, you can do this by setting the proxy_set_header X-Forwarded-Proto https; config. Refer this issue to learn more.

Getting Started

Deployment Methods

Cloud Providers

Configuration

Integrations

Maintenance

Runbooks

Others

Deploy Chatwoot on Kubernetes using Helm Charts

Prerequisites

Installing the chart

Uninstalling the chart

Parameters

Chatwoot Image parameters

Chatwoot Environment Variables

Email setup for conversation continuity (Incoming emails)

Postgres variables

Redis variables

Logging variables

Third party credentials

Autoscaling

Install with custom parameters

Postgres

Redis

Autoscaling

Upgrading

Troubleshooting

pod has unbound immediate PersistentVolumeClaims

ActionController::InvalidAuthenticityToken HTTP Origin header

​Prerequisites

​Installing the chart

​Uninstalling the chart

​Parameters

​Chatwoot Image parameters

​Chatwoot Environment Variables

​Email setup for conversation continuity (Incoming emails)

​Postgres variables

​Redis variables

​Logging variables

​Third party credentials

​Autoscaling

​Install with custom parameters

​Postgres

​Redis

​Autoscaling

​Upgrading

​Troubleshooting

​pod has unbound immediate PersistentVolumeClaims

​ActionController::InvalidAuthenticityToken HTTP Origin header

Prerequisites

Installing the chart

Uninstalling the chart

Parameters

Chatwoot Image parameters

Chatwoot Environment Variables

Email setup for conversation continuity (Incoming emails)

Postgres variables

Redis variables

Logging variables

Third party credentials

Autoscaling

Install with custom parameters

Postgres

Redis

Autoscaling

Upgrading

Troubleshooting

pod has unbound immediate PersistentVolumeClaims

ActionController::InvalidAuthenticityToken HTTP Origin header