Updating
The update screen, the two ways it can work, and the commands to run when the panel is not allowed to.
System → Setup & licensing is the update machinery. It is deliberately verbose: it shows the version, the
channel, the commands it would run, and a line per step as they happen.
What is on the screen
| Part | What it does |
|---|---|
| Installed version | What this copy is, read from the folder |
| Channel | Which line of releases it follows |
| Administrators | How many exist. Zero is a problem worth noticing |
| Where newer copies come from | A repository or a manifest address, saved once |
| Check for a newer copy | Asks, and reports what it found |
| The commands | Shown before they run, and whether the panel is allowed to run them |
| The licence record | Who this installation is for |
The two ways it can work
ALLOW_SELF_UPDATE | What happens |
|---|---|
| Unset | The screen checks, shows the exact commands, and does not run them |
Exactly 1 | The screen runs them, and writes down each step as it happens |
The first is the honest default for a host with no shell or a folder the app does not own: telling you what to type is better than pretending. The second belongs on a machine whose folder you control, and it is the reason that variable exists rather than being always on.
`1` means `1`
The value has to be exactly 1. true, yes and on are all read as "not
set", which is deliberate: this is a switch that runs commands on your server,
and it should be hard to turn on by accident.
Updating by hand
The commands the panel runs are the commands you would run. In the folder:
# 1. Keep a copy of what you have, if the release notes mention a schema change
# System → Backups & exports, take a snapshot, download it.
# 2. The code
git pull # or unpack the newer copy over the folder
# 3. The packages
pnpm install
# 4. The backend, which is a separate deployment
npx convex deploy
# 5. The app
pnpm build
# 6. Restart whatever runs pnpm startThen open System → Status & health and confirm the four checks, and System → Audit log for anything that
changed on its own during the update.
Before you update
Read what changed. A release that mentions a schema change or a migration is a release to treat carefully.
System → Backups & exports.Pick a quiet moment. A restart interrupts running turns, and a migration may hold a table for a moment.
Know how you would go back: the previous copy of the folder, and the snapshot.
After you update
| Check | Where |
|---|---|
| It is up | System → Status & health |
| The version moved | System → Setup & licensing |
| Nothing changed that you did not expect | System → Audit log |
| Sign in works, including a social button | /sign-in |
| Mail works | Brand → Emails, send a test |
| The documentation matches | Open /docs and read the page that covers the change |
A rollback is not only the code
Going back to an older copy of the folder while the deployment has already moved forward can leave the app expecting a field the backend no longer writes. If a release required a deploy, rolling back means rolling the deployment back too, from the Convex dashboard, and the snapshot is the third piece.
Keeping the documentation current
This manual is content in the folder, under content/docs/. It is not generated from the code, so a release that
changes a screen should change the page that describes it. Adding a page is adding an MDX file, and the order in
the sidebar comes from a meta.json beside the files. If a screen and a page disagree, the page is wrong: the
screen is what people are actually using.