Skip to content

docs: clarify specific-version upgrade guidance #562

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sojan-official merged 3 commits into from
May 27, 2026
Merged

docs: clarify specific-version upgrade guidance #562

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
959093b
docs: add cwctl specific-version upgrade guidance
sojan-official Feb 26, 2026
46009cb
docs: clarify specific version upgrade guidance
sojan-official May 27, 2026
f4c5c34
docs: mention branch upgrades for cwctl
sojan-official May 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion self-hosted/deployment/chatwoot-ctl.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,24 @@ 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.
</Note>

### Upgrading to a specific version or branch

`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
Comment thread
sojan-official marked this conversation as resolved.

# Upgrade from a branch
sudo cwctl -U develop
```

<Warning>
`-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.
</Warning>

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

To set up Nginx with SSL after initial setup(if you answered `no` to webserver/SSL setup during the first install)
Expand Down Expand Up @@ -97,4 +115,4 @@ To check the version of Chatwoot CTL,

```bash
sudo cwctl --version
```
```
4 changes: 4 additions & 0 deletions self-hosted/deployment/docker.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

<Note>
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.
</Note>

After that you can pull the new image and start using them:

```bash
Expand Down
14 changes: 11 additions & 3 deletions self-hosted/deployment/upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,23 +9,31 @@ sidebarTitle: Upgrade
Whenever a new version of Chatwoot is released, use the following steps to upgrade your instance.

<Note>
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).
</Note>

<Note>
If you are on an older version of Chatwoot(< 2.7), follow the [manual upgrade steps](/self-hosted/deployment/linux-vm#upgrading-to-a-newer-version-of-chatwoot) if you face errors with `cwctl`.
</Note>

```bash
cwctl --upgrade
sudo cwctl --upgrade
```

This upgrade method is applicable for all manual linux installations including installation using aws marketplace.
<Note>
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.
</Note>

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.

<Note>
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.
</Note>

```bash
docker-compose down
docker-compose pull
Expand Down
Loading