How to Rollback a Software-Only Upgrade

If you're hosting Talkyard on-premise, and need to rollback a software-only upgrade to the Talkyard version running before the upgrade, then follow the below steps.

What's a software-only upgrade? That's when the Talkyard software, like the application server, HTTP server, memory cache, etc gets upgraded — but the database that stores the discussions, user accounts, etc, isn't changed.

The other type of upgrade is a database migration. For example, Talkyard adding tables or columns to the above-mentioned database. To rollback such an upgrade, go to this page instead: TBD.

How do you know if a new Talkyard version is a software-only upgrade, or if it also does a database migration? You'll check the release notes — here: https://www.talkyard.io/forum/latest/releases. Later, maybe the version number can tell you what kind of upgrade it is — maybe v0.2022.23-(sha-hash)-swo or -dbm for "-software-only upgrade" or "database migration", respectively.

Step by step:

1. Disable automatic upgrades

Login to your Talkyard server. Let's see if auto upgrades are enabled — it'd be annoying if Talkyard upgraded itself again automatically, wouldn't it?

sudo -i  # become root
crontab -l | grep 'talkyard.*upgrade'   # 'l' means 'list jobs'

If that prints nothing, auto upgrades are disabled (unless you've renamed scripts and directories).

If something gets printed, though, then, backup the current cron jobs, just in case:

pwd  # remember where you are
crontab -l >> crontab-backup.bak

Thereafter, edit the cron jobs: delete the line that calls ...talkyard ... upgrade-if-needed.sh... :

crontab -e   # 'e' means 'edit'

Afterwards, type crontab -l again to see if it worked, that is, if the ...upgrade-if-needed... line is gone, but the others are still there.

2. Type the version number to rollback to

Check what version is currently in use — it's in the .env file:

cd /opt/talkyard
grep -C3 VERSION .env

That'll print something like:

# Which version of Talkyard to use.
# Don't edit manually; instead, scripts/upgrade-if-needed.sh sets it to the correct value.
VERSION_TAG=v0.2022.10-d09071401

You'll also find it here, if the server is up and running: https:// talkyard server /-/build-info — the "docker tag" line.

Now, let's say you want to revert to the previous version — but which version number is that? Look in the versions log file:

root@your-server:/opt/talkyard# tail -n5 versions/version-tags.log
v0.2022.06-4f3b8df07
v0.2022.07-c58adddcb
v0.2022.08-5528484f5
v0.2022.09-e39ae474a   <—— the previous version
v0.2022.10-d09071401   <—— the current version

So, the previous version is v0.2022.09-e39ae474a. Copy that version number.

Edit the .env file, and paste that version number: (it's ok to edit manually, since you know what you're doing)

# Which version of Talkyard to use.
# Don't edit manually; instead, scripts/upgrade-if-needed.sh sets it to the correct value.
# No, wait:
# VERSION_TAG=v0.2022.10-d09071401
# Rolling back to this instead, because ______ :
VERSION_TAG=v0.2022.09-e39ae474a

It's good if you add # comment lines telling yourself and your co-workers what you're doing.

3. Restart, to rollback

When you shutdown Talkyard, when it starts again, it'll use the Docker images version v0.2022.09-e39ae474a (or whatever previous version you specified) instead:

docker-compose kill search app  # stopping these first avoids harmless error log messages
docker-compose down   # deletes all containers with the current version
docker-compose up -d  # starts the previous version (the one in the .env file)
./view-logs -f app    # does it seem to work?

(The database contents isn't affected by you deleting the containers — the database files are in /opt/talkyard/data/rdb/ and last across container deletions and upgrades.)

After a minute or two, https:// talkyard server /-/build-info should show the previous version number.

4. Upgrade again

Some time later, you can upgrade manually to the newest version:

cd /opt/talkyard 
./scripts/upgrade-if-needed.sh

Or, if you want to upgrade to a specific version, edit the VERSION_TAG=... in the .env file, and instead do step 3 above, i.e. shutdown and restart, to change to that version.

Add a reminder in your / your-company's calendar about enabling automatic upgrades again. To enable auto upgrades:

cd /opt/talkyard
scripts/schedule-automatic-upgrades.sh