From 959093bb734db777d790dfb2ecf89d5b3a4a2c05 Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Thu, 26 Feb 2026 00:57:28 -0800 Subject: [PATCH 1/3] docs: add cwctl specific-version upgrade guidance --- self-hosted/deployment/chatwoot-ctl.mdx | 14 +++++++++++++- self-hosted/deployment/upgrade.mdx | 4 ++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/self-hosted/deployment/chatwoot-ctl.mdx b/self-hosted/deployment/chatwoot-ctl.mdx index 09ad343a..82b0f91a 100644 --- a/self-hosted/deployment/chatwoot-ctl.mdx +++ b/self-hosted/deployment/chatwoot-ctl.mdx @@ -53,6 +53,18 @@ sudo cwctl --upgrade This will upgrade your Chatwoot instance to the latest stable release. If you are running a custom branch in production do not use this to upgrade. +To upgrade to a specific Chatwoot version, use `-U`/`--Upgrade` with a git ref. + +```bash +sudo cwctl -U +# example +sudo cwctl -U v4.3.0 +``` + + +`-u`/`--upgrade` upgrades to latest stable (`master`), while `-U`/`--Upgrade` upgrades to a specific git ref and is currently experimental. Upgrades can fail when your Chatwoot repo has local code changes, so keep production changes clean and take backups before upgrading. Under the hood, `-U` performs a `git checkout ` followed by `git pull`. + + ### Setup Nginx with SSL after installation To set up Nginx with SSL after initial setup(if you answered `no` to webserver/SSL setup during the first install) @@ -97,4 +109,4 @@ To check the version of Chatwoot CTL, ```bash sudo cwctl --version -``` \ No newline at end of file +``` diff --git a/self-hosted/deployment/upgrade.mdx b/self-hosted/deployment/upgrade.mdx index 35c9c6e2..130079a4 100644 --- a/self-hosted/deployment/upgrade.mdx +++ b/self-hosted/deployment/upgrade.mdx @@ -20,6 +20,10 @@ If you are on an older version of Chatwoot(< 2.7), follow the [manual upgrade st cwctl --upgrade ``` + +To reduce risk of breakages, upgrade iteratively across versions instead of skipping many releases in one jump (for example, avoid upgrading directly from `v4.1` to `v4.10`). + + This upgrade method is applicable for all manual linux installations including installation using aws marketplace. ## Docker From 46009cbe5daefd2c731943eab1ebbe4df7df20c1 Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Wed, 27 May 2026 16:21:05 +0530 Subject: [PATCH 2/3] docs: clarify specific version upgrade guidance --- self-hosted/deployment/chatwoot-ctl.mdx | 14 ++++++++------ self-hosted/deployment/docker.mdx | 4 ++++ self-hosted/deployment/upgrade.mdx | 12 ++++++++---- 3 files changed, 20 insertions(+), 10 deletions(-) diff --git a/self-hosted/deployment/chatwoot-ctl.mdx b/self-hosted/deployment/chatwoot-ctl.mdx index 82b0f91a..86703dc9 100644 --- a/self-hosted/deployment/chatwoot-ctl.mdx +++ b/self-hosted/deployment/chatwoot-ctl.mdx @@ -53,17 +53,19 @@ sudo cwctl --upgrade This will upgrade your Chatwoot instance to the latest stable release. If you are running a custom branch in production do not use this to upgrade. -To upgrade to a specific Chatwoot version, use `-U`/`--Upgrade` with a git ref. +### Upgrading to a specific version + +`cwctl` also supports experimental upgrades to a specific Chatwoot version. This is useful when an instance is several releases behind and needs to be upgraded through intermediate versions instead of jumping directly to the latest release. ```bash -sudo cwctl -U -# example sudo cwctl -U v4.3.0 ``` - -`-u`/`--upgrade` upgrades to latest stable (`master`), while `-U`/`--Upgrade` upgrades to a specific git ref and is currently experimental. Upgrades can fail when your Chatwoot repo has local code changes, so keep production changes clean and take backups before upgrading. Under the hood, `-U` performs a `git checkout ` followed by `git pull`. - + +`-U`/`--Upgrade` is experimental and is not recommended for production environments without testing. When using a release tag like `v4.3.0`, Git may print a pull warning because tags are checked out in a detached HEAD state. + + +Before upgrading, take a backup, review the release notes for the target version, and keep the Chatwoot repository clean. The upgrade will abort if local code changes are detected. ### Setup Nginx with SSL after installation diff --git a/self-hosted/deployment/docker.mdx b/self-hosted/deployment/docker.mdx index ec645a5d..dad257dc 100644 --- a/self-hosted/deployment/docker.mdx +++ b/self-hosted/deployment/docker.mdx @@ -181,6 +181,10 @@ To set up the database for the first time, you must run `rails db:chatwoot_prepa If you're not using the `latest` or `latest-ce` tag, you first need to change the desired tag in your docker-compose file. + +If your installation is very old, upgrade iteratively through intermediate Docker image tags instead of jumping directly to the latest image. Review the release notes between versions and run `rails db:chatwoot_prepare` after each upgrade. + + After that you can pull the new image and start using them: ```bash diff --git a/self-hosted/deployment/upgrade.mdx b/self-hosted/deployment/upgrade.mdx index 130079a4..389a751b 100644 --- a/self-hosted/deployment/upgrade.mdx +++ b/self-hosted/deployment/upgrade.mdx @@ -9,7 +9,7 @@ sidebarTitle: Upgrade Whenever a new version of Chatwoot is released, use the following steps to upgrade your instance. -To install `cwctl`, refer [this](#install-or-upgrade-chatwoot-cli) section below. +To install `cwctl`, refer to the [Chatwoot CTL guide](/self-hosted/deployment/chatwoot-ctl#install-or-upgrade-chatwoot-ctl). @@ -17,19 +17,23 @@ If you are on an older version of Chatwoot(< 2.7), follow the [manual upgrade st ```bash -cwctl --upgrade +sudo cwctl --upgrade ``` -To reduce risk of breakages, upgrade iteratively across versions instead of skipping many releases in one jump (for example, avoid upgrading directly from `v4.1` to `v4.10`). +Before upgrading, review the release notes for versions between your current installation and the target version. If your installation is very old, upgrade iteratively through intermediate versions instead of jumping directly to the latest release. This helps you apply required migrations and configuration changes in the expected order. Test the upgrade on a staging instance first. -This upgrade method is applicable for all manual linux installations including installation using aws marketplace. +This upgrade method is applicable for all manual Linux installations, including installations using AWS Marketplace. ## Docker Update the images using the latest image from chatwoot. + +If your installation is very old, upgrade iteratively through intermediate Docker image tags instead of jumping directly to the latest image. Review the release notes between versions, update the image tag in your Docker Compose file for each target version, and run the database preparation step after each upgrade. + + ```bash docker-compose down docker-compose pull From f4c5c34be22f30d38404d632a97bb42eafdaf02e Mon Sep 17 00:00:00 2001 From: Sojan Jose Date: Wed, 27 May 2026 16:56:06 +0530 Subject: [PATCH 3/3] docs: mention branch upgrades for cwctl --- self-hosted/deployment/chatwoot-ctl.mdx | 8 ++++++-- self-hosted/deployment/upgrade.mdx | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/self-hosted/deployment/chatwoot-ctl.mdx b/self-hosted/deployment/chatwoot-ctl.mdx index 86703dc9..52c85ca2 100644 --- a/self-hosted/deployment/chatwoot-ctl.mdx +++ b/self-hosted/deployment/chatwoot-ctl.mdx @@ -53,12 +53,16 @@ sudo cwctl --upgrade This will upgrade your Chatwoot instance to the latest stable release. If you are running a custom branch in production do not use this to upgrade. -### Upgrading to a specific version +### Upgrading to a specific version or branch -`cwctl` also supports experimental upgrades to a specific Chatwoot version. This is useful when an instance is several releases behind and needs to be upgraded through intermediate versions instead of jumping directly to the latest release. +`cwctl` also supports experimental upgrades to a specific Chatwoot version or branch. This is useful when an instance is several releases behind and needs to be upgraded through intermediate versions instead of jumping directly to the latest release. You can also use this to upgrade from a branch such as `develop`. ```bash +# Upgrade to a specific released version sudo cwctl -U v4.3.0 + +# Upgrade from a branch +sudo cwctl -U develop ``` diff --git a/self-hosted/deployment/upgrade.mdx b/self-hosted/deployment/upgrade.mdx index 389a751b..90b31997 100644 --- a/self-hosted/deployment/upgrade.mdx +++ b/self-hosted/deployment/upgrade.mdx @@ -21,7 +21,7 @@ sudo cwctl --upgrade ``` -Before upgrading, review the release notes for versions between your current installation and the target version. If your installation is very old, upgrade iteratively through intermediate versions instead of jumping directly to the latest release. This helps you apply required migrations and configuration changes in the expected order. Test the upgrade on a staging instance first. +Before upgrading, review the release notes for versions between your current installation and the target version. If your installation is very old, upgrade iteratively through intermediate versions instead of jumping directly to the latest release. This helps you apply required migrations and configuration changes in the expected order. Use the [specific version upgrade flow](/self-hosted/deployment/chatwoot-ctl#upgrading-to-a-specific-version-or-branch) when you need to stop at an intermediate Linux VM version, and test the upgrade on a staging instance first. This upgrade method is applicable for all manual Linux installations, including installations using AWS Marketplace.