Skip to content

docs: add cwctl specific-version upgrade instructions and iterative upgrade note #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

Open
sojan-official wants to merge 1 commit into
base: main
Choose a base branch
from
+17 −1
Open

docs: add cwctl specific-version upgrade instructions and iterative upgrade note #562

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 13 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,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.
</Note>

To upgrade to a specific Chatwoot version, use `-U`/`--Upgrade` with a git ref.

```bash
sudo cwctl -U <VERSION>
# example
sudo cwctl -U v4.3.0
```

<Note>
`-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 <VERSION>` followed by `git pull`.
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot Feb 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Avoid plain git pull after checking out a version tag

The new guidance says -U performs git checkout <VERSION> followed by git pull, and the example uses v4.3.0 (a release tag). When <VERSION> is a tag, checkout puts the repo in detached HEAD, where git pull fails with You are not currently on a branch ... git pull <remote> <branch>, so users following this documented path can hit an upgrade failure in production unless they pass a tracked branch name instead of a version tag.

Useful? React with 👍 / 👎.

</Note>

### 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 +109,4 @@ To check the version of Chatwoot CTL,

```bash
sudo cwctl --version
```
```
4 changes: 4 additions & 0 deletions self-hosted/deployment/upgrade.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ If you are on an older version of Chatwoot(< 2.7), follow the [manual upgrade st
cwctl --upgrade
```

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

This upgrade method is applicable for all manual linux installations including installation using aws marketplace.

## Docker
Expand Down