As life goes on, software receives updates and we maintainers have to catch up by upgrading our platforms. In my case, I maintain a #Mastodon and a #Firefish instances, both under #Docker, running in separated #RaspberryPi machines. I personally have an eye for new versions and book some time to keep the instance up to date, and feel entitled to highlight some differences between them when it comes to upgrade tasks.

Overview

In this small article I quickly go through the steps I do since the need of upgrading until the job is done, just to compare the tasks to do in both instances. And these steps are:

1. Disclaimer
2. Spotting new versions
3. Release notes
4. Maintaining customisations
5. Docker build
6. DB Migrations
7. Spotting the upgraded version
8. Wrapping up

1. Disclaimer

Before going deeper just some context. At this point of time both instances are running in a Raspberry Pi 4 with 8GB, both booting up in a USB3 SSD, both instances under Docker, both maintaining the media externalised in an external CDN and both receiving the traffic behind a reverse proxy located in a yet another Raspberry Pi that also behaves as my local network's DNS server.

The only infrastructural difference between both is that the Raspberry Pi that hosts the Firefish instance also hosts my personal Pixelfed dockerised instance. Not really an important point but something to note when it comes to the overall load of the machine.

2. Spotting new versions

Sometimes the news come to you more than you actively searching for them, or at least this is what happens to me most of the times for Mastodon, as my Timeline fills ups with colleagues talking about the new version.

Other times I let my Janitor bot to publish a note in my @external_updates account announcing new changes being pushed into main.

What is true is that while both maintain a tag based versioning and a CHANGELOG file, the level of documentation is significally different even not great in both.

For example, at this point of time Mastodon just released the new v4.2.3 but its CHANGELOG file still mentions that the latest is v4.2.1.

In the other hand, Firefish has been pretty inconsistent until now regarding publishing the tag based versions. And I say until now because after observing it for a couple of months, it has been the last week with the version v1.0.5-RC that got it’s related CHANGELOG correct entry.

I am relating to these tag based versions because you don’t actually want to “just checkout the main branch” and build: you want to attach yourself to a specific version assuming that the team ensured the correct behaviour and therefore tagged the code in an specific point of time. That’s why you need a version to refer and a paired CHANGELOG to relate the changes and fixes included.

3. Release notes

And related to the previous section, when it comes to the steps to follow to bring the new version to your system, you need to rely in clear instructions that tell you what to execute and what to expect. Do we have to apply changes in the DB? Do we have changes in dependency versions?

For Mastodon this is a clear THANK YOU, as every release comes together with release notes that tells explicitly changes en versions, migrations to apply, actions that apply for Docker and non-Docker instances. Check Out the Release Notes for v4.2.3

For Firefish it is really disappointing. The body for the last release note spots some valuable changes but not really instructions for the upgrade. The last note that contains upgrade instructions is for the v1.0.3 version and it is certainly small and not really useful. The last useful information comes from the note for the v1.0.0 as it is a rebranding from the old Calckey naming.

Personally, I upgrade quite confidently my Mastodon instance and I feel like gambling when I upgrade my Firefish instance. I could understand any admin discarding Firefish for its lack of documentation effort, even loosing the great set of features that places it in front on Mastodon.

4. Maintaining customisations

My both instances are slightly customised, meaning personalisations are only at icons and public images level. This means that it’s important for me that the file structure stays stable as much as possible, so that maintaining the customisations along the upgrades stays easy and stable.

Here in both cases the process is very easy. I have a set of files that live on top of the official repository and I git stash and git stash pop every time I fetch a new set of changes. Easy peasy.

5. Docker build

I don’t want to enter into the maintenance of the individual components of every instance’s architecture. Nowadays we have Docker that allows us to spawn an instance with all the related infrastructure isolated from the actual hardware. And the owners do a good job maintaining a Dockerfile that brings all together.

Even in both cases we can access to official Docker images (here for Mastodon and Firefish), as long as I want to keep my customisations, I need to build my own container images (that for the record I upload here)

The build itself is uncomplicated in both cases, just having the repository cloned and up-to-date in the target machine and trigger a docker build -t instance:20231208 -f Dockerfile from the instance folder is enough. For example, this is the full process I documented for the upgrade of Mastodon to the v4.2.0, that I followed for the further upgrades to v4.2.1 and v4.2.3.

The build for the Mastodon instance is relatively fast on a Raspberry Pi 4. It takes around 30 minutes. In the other hand, Firefish takes a good 2 hours, really really long in comparison.

6. DB Migrations

One of the things that one wants when it comes to upgrading any software is previsibility. I want to know what is going to happen, how much time will it take, and if I will need to do any task outside from the guidelines. That’s why it is so important to have proper release notes.

For the possible DB migrations, Mastodon make you trigger them manually. The release notes tell you if they are needed at all, so in case there are no changes in the DB you can be confident that if the image building fails you can always return to the previous version with no harm.

Firefish in the other hand executes the possible migrations internally while starting up the instance. From our point of view, it happens totally transparent and one only notice it if monitoring the logs with docker logs -f [container_id]. So, how can I know that this upgrade comes with migrations? I don’t. Cross fingers and go for it. That’s really bad, and also due to the lack of proper documentation.

7. Spotting the upgraded version

And at the end of the road, after spending some time building (maybe hours) and crossing fingers while starting the instance the first time after it, how can you know that the instance now is running the new version?

For Mastodon we have to go to the “First steps” page and look for the version at the bottom. There appears the version at the end of the site links.

For Firefish is nicer, with a pop up appearing that announces the new version, the first time after the upgrade.

8. Wrapping up

So, after all, what is the experience as an admin of an instance at upgrading the version of the platform? For Mastodon is what one would expect: previsible, measurable, documented (mostly as expected), reliable. For Firefish feels casual, as a home project would be, with minimal to no-documentation and ready to say good bye to the whole instance in case it fails.

Previous Post Next Post