Updating
How to update a self-hosted Modbot, what happens to the database when the new version starts, and what the version numbers mean.
Updating Modbot means running a newer build of the server image against the same database. There is no update command and no database step for you to run: the new version updates the database's tables itself when it starts.
How you find out there is one
Modbot checks for a newer release a minute after it starts and every six hours after that, and shows what it found on the This install card under Settings, Server:
| Row | What it is |
|---|---|
| Version | The release this server is running. Point at it to see the exact commit and branch. |
| Install | The hosting platform Modbot recognised, such as Railway, or self-hosted. |
| Newest | The newest release there is. |
| Pull | The image and tag to pull, shown only when there is a newer release. |
Modbot never updates itself. It never pulls an image, never restarts itself and never touches your host. It tells you a newer version exists and what to pull; everything below is yours to do when it suits you.
The question goes to cloud.modbot.co. Nothing about your deployment is sent — no id, no group, no
version, no account — and nothing is recorded: everyone gets the same answer out of one cached
copy. For that reason MODBOT_CLOUD_DISABLED does not turn it off; that variable turns off the
things that do send something, and an operator who turned those off should still hear about a
security fix. The Check for updates switch on the same card is what turns it off, and turning
it off clears what Modbot last heard.
If a check fails, the card shows why and keeps the version it last heard of, because "we could not ask today" is not "you are up to date".
Before you update
Take a backup of the database. The new version may change its tables when it starts, and going back to an older version does not undo those changes. See PostgreSQL.
Note the Version on the This install card under Settings, Server — point at it to see the commit — so you can tell afterwards that the update took.
Updating on Railway
Deploy the newer commit of the repository to your Modbot service, the same way it was deployed the first time. If your service is connected to your own fork, bring the fork up to date first.
Railway builds the image and starts the new deployment. It counts as healthy once /health/ready
answers, which only happens after the database has been updated. With the 300 second timeout from
Modbot's Railway configuration, a slow update is not mistaken for a failed one. See
Railway.
Updating with Docker
If you set Modbot up with the install script, go to the folder it wrote and pull:
docker compose pull
docker compose up -dWith the published image, pull the newer tag and replace the container:
docker pull ghcr.io/modbot/modbot:latest
docker stop modbot && docker rm modbot
docker run -d --name modbot --network modbot -e DATABASE_URL=postgres://modbot:choose-a-long-password@modbot-db:5432/modbot -p 8080:8080 -v modbot-logs:/app/logs --restart unless-stopped ghcr.io/modbot/modbot:latestTo move to one release and stay on it, use its version as the tag instead of latest. See
Docker for the tags.
With an image you built yourself, get the newer code, build it again, and replace the container:
git pull
docker build -t modbot .
docker stop modbot && docker rm modbot
docker run -d --name modbot --network modbot \
-e DATABASE_URL=postgres://modbot:choose-a-long-password@modbot-db:5432/modbot \
-p 8080:8080 \
-v modbot-logs:/app/logs \
--restart unless-stopped \
modbotUse the same docker run options you started it with the first time, including any volume for
evidence. With Docker Compose it is:
git pull
docker compose up -d --buildYour data is in the database's volume, so replacing the Modbot container loses nothing. See Docker.
What happens when the new version starts
- Modbot connects to the database, waiting for it if needed.
- It compares the database's tables with what this version expects. If they match, the log says
Database schema is up to date. If not, it logs how many changes it is applying, and applies them. - Only then does it start answering requests and health checks.
If applying the changes fails, the new version logs why in one sentence and does not start. It will not run against a half-updated database. Restore your backup, or fix the cause named in the log and start it again.
Version numbers
Modbot has two version numbers, and they answer different questions.
The release version
A calendar version, year.month.patch, such as 2026.9.1:
- the year and the month the release was made,
- a patch number that starts again at 0 each month.
The parts are not padded with zeros, so compare them part by part as numbers: 2026.9.10 is newer
than 2026.9.2.
It is shown as Version on the This install card, and returned by GET /api/version, which
needs no sign-in.
An image built with the repository's Dockerfile does not set a release number, so Version
shows the default written in the source at that commit. Pointing at Version shows the exact
commit you are running.
The API version
A whole number that only goes up when something the companion depends on changes in a way older clients cannot handle. It does not change with every release.
Each server speaks a range of API versions, not just one. GET /api/version returns it:
{
"version": "2026.9.0",
"apiVersion": 1,
"apiVersionMinimum": 1
}A companion picks the highest version both sides speak. The project's rule is that a server keeps speaking the current API version and at least the two before it, and never drops one less than 12 months old. That is why installing the newest companion is always the right choice, even for a moderator whose groups run Modbots on different versions.
If a client and a server have no version in common, the client is told
This server speaks API versions followed by the range.
The companion updates separately
Updating your server does not update anyone's companion. Because servers speak a range of API versions, a client does not need to match the server's release. The client checks for its own updates. See Installing the companion.