Skip to content

v4.3.0
Compare
Choose a tag to compare
@ClearlyClaire ClearlyClaire released this 08 Oct 12:24
· 130 commits to stable-4.3 since this release
v4.3.0
e272cf5

This is the first tagged glitch-soc release, corresponding to Mastodon's v4.3.0, which release notes are reproduced below.

Upgrade overview

This release contains upgrade notes that deviate from the norm:

‼️ Requires new encryption secrets environment variables
⚠️ The minimal supported version for PostgreSQL has been bumped to 12, and PostgreSQL versions 14.0 to 14.3 are not supported as they contain a critical data-corruption bug
⚠️ The minimal supported version for Ruby has been bumped to 3.1
⚠️ The minimal supported version for Node.js has been bumped to 18
⚠️ Requires rebuilding Elasticsearch accounts index
⚠️ We switched from yarn 1 to yarn 4, and recommend using corepack
⚠️ The Docker image has been split in two separate images
⚠️ Rolling updates from versions earlier than Mastodon 4.2 are not supported
⚠️ StatsD integration has been removed, replaced by OpenTelemetry integration
⚠️ ImageMagick is being deprecated and may be removed in a future version
ℹ️ Requires streaming API restart
ℹ️ Requires database migrations
ℹ️ The logging format of the streaming server has changed

For more information, scroll down to the upgrade instructions section.

Changelog

The following changelog entries focus on changes visible to users, administrators, client developers or federated software developers, but there has also been a lot of code modernization, refactoring, and tooling work, in particular by @mjankowski.

Security

Added

Changed

Removed

Fixed

Upgrade notes

To get the code for v4.3.0, use git fetch && git checkout v4.3.0.

Note

As always, make sure you have backups of the database before performing any upgrades. If you are using docker-compose, this is how a backup command might look: docker exec mastodon_db_1 pg_dump -Fc -U postgres postgres > name_of_the_backup.dump

Dependencies

External dependencies have changed since v4.2.12, with the Ruby, PostgreSQL and Node.js minimum version being higher. In addition, an optional dependency on libvips has been introduced to replace ImageMagick.

  • Ruby: 3.1 or newer
  • PostgreSQL: 12 or newer. PostgreSQL versions 14.0 to 14.3 are not supported as they contain a critical data-corruption bug (see below)
  • Elasticsearch (recommended, for full-text search): 7.x (OpenSearch should also work)
  • LibreTranslate (optional, for translations): 1.3.3 or newer
  • Redis: 4 or newer
  • Node: 18 or newer
  • ImageMagick (optional if using libvips): 6.9.7-7 or newer
  • libvips (optional, instead of ImageMagick): 8.13 or newer

PostgreSQL 14.0 to 14.3 bug

PostgreSQL versions 14.0 to 14.3 are not supported as they contain a critical data-corruption bug.

If you run one of those versions, please upgrade to the latest PostgreSQL 14 minor version (14.13 at the time of the release) before upgrading Mastodon. Upgrading a PostgreSQL without bumping the major version should only a require a restart of your database after your packages/containers have been updated, not any data migration.

If you are using Docker Compose to run PostgreSQL, please ensure that the image field does not specify the patch version (for example, it can be 14, or 14-alpine, to tell Docker to use the latest image with this tag), then:

  • stop the database service: docker compose down db
  • pull the latest version for this tag: docker compose pull db
  • restart the service: docker compose up -d

If you want to use this opportunity to upgrade to a later PostgreSQL major version, then you will need to migrate your PostgreSQL data directory. You can find more informations about this process in the official documentation.

Active Record encryption secrets configuration

Mastodon now requires new environment variables for secret keys to be set.
Generate new secrets and set ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY, ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT, and ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY accordingly before restarting Mastodon.

All Mastodon processes need to have access to them, so if you use multiple puma (mastodon-web) and sidekiq (mastodon-sidekiq) nodes, make sure to copy the secrets to all of them. Do not change them once they are set.

Such secrets can be generated by running bin/rails db:encryption:init.

Docker image split

The official Docker image has now been split in two smaller images:

  • ghcr.io/mastodon/mastodon, which does not contain the streaming server anymore
  • ghcr.io/mastodon/mastodon-streaming, which contains only the streaming server

The docker-compose.yml file shipped with Mastodon has been updated accordingly. If you use something else, you will need to update your configuration.

Cookies and rolling updates

Cookies issued by Mastodon are now using SHA256 digests. To ensure you are not losing user sessions, do not perform a rolling update from versions of Mastodon earlier than v4.2.0.

That is, either completely stop Mastodon before updating it, or update to the latest v4.2 then update to v4.3.

Yarn 4 and corepack

We have switched from Yarn 1 to the more modern and more efficient Yarn 4.

The recommended way is to use corepack, which is normally distributed with NodeJS. To do so, do corepack enable, then, in Mastodon's directory, once you have checked out v4.3.0, corepack prepare.

You can also install yarn 4 directly if you don't want to or can't use corepack.

ImageMagick deprecation and libvips replacement

ImageMagick support in Mastodon is being deprecated in favor of libvips, a more efficient library to process image attachments.

To use libvips instead of ImageMagick, install libvips 8.13 or newer, and set the MASTODON_USE_LIBVIPS environment variable to true.

The official Mastodon docker images use libvips instead of ImageMagick, and we recommend you do the same, but ImageMagick is still supported in this version for older distributions that do not include a recent enough version of libvips.

StatsD removal and OpenTelemetry integration

StatsD support has been removed, after being deprecated in 4.2.0.

If you want to have metrics for your Sidekiq queues (queue size, latency…), you can use https://github.com/Strech/sidekiq-prometheus-exporter

Mastodon now also supports exporting tracing data using OpenTelemetry. This can be used to get detailed performance data, as well as monitoring for backend errors. More informations on how to configure it in our docs (https://docs.joinmastodon.org/admin/config/#otel)

Update steps

The following instructions are for updating from 4.2.12.

If you are upgrading directly from an earlier release, please carefully read the upgrade notes for the skipped releases as well, as they often require extra steps such as database migrations. If you are upgrading from a pre-4.2 version, please check the “Cookies and rolling updates” section above.

If you are updating from 4.3.0-beta.1, 4.3.0-beta.2 or 4.3.0-rc.1, only a few of these steps are relevant, see the next section.

Non-docker

Tip

The charlock_holmes gem may fail to build on some systems with recent versions of gcc.
If you run into such an issue, try BUNDLE_BUILD__CHARLOCK_HOLMES="--with-cxxflags=-std=c++17" bundle install.

  1. If you are using rbenv, update the list of available versions and install the proper Ruby version by doing RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install in the Mastodon install directory (e.g. /home/mastodon/live)
  2. Install yarn 4 (if you use corepack, just do corepack prepare). See the “Yarn 4 and corepack” section for more information.
  3. Install dependencies with bundle install and yarn install --immutable
  4. Generate secrets by running RAILS_ENV=production bin/rails db:encryption:init, then copy them to your .env.production (copy it across all your nodes if you use multiple ones)
  5. Precompile the assets: RAILS_ENV=production bundle exec rails assets:precompile
  6. Run the pre-deployment database migrations by specifying the SKIP_POST_DEPLOYMENT_MIGRATIONS=true environment variable: SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
  7. Restart all Mastodon processes. If you are updating directly from a Mastodon version earlier than 4.2.0, see the “Cookies and rolling updates” section.
  8. Run the post-deployment database migrations: RAILS_ENV=production bundle exec rails db:migrate
  9. If you use Elasticsearch or OpenSearch, rebuild the account search index with RAILS_ENV=production bin/tootctl search deploy --only=accounts

When using docker

  1. Generate secrets by running docker-compose run --rm web bin/rails db:encryption:init, then copy them to your .env.production (make sure to copy them across all your Mastodon nodes as they will all need access to these secrets)
  2. Run the pre-deployment database migrations by specifying the SKIP_POST_DEPLOYMENT_MIGRATIONS=true environment variable: docker-compose run --rm -e SKIP_POST_DEPLOYMENT_MIGRATIONS=true web bundle exec rails db:migrate
  3. Make sure your Docker configuration has been updated to take the Docker image split into account (See the “Docker image split” section above)
  4. Restart all Mastodon processes. If you are updating directly from a Mastodon version earlier than 4.2.0, see the “Cookies and rolling updates” section.
  5. Run the post-deployment database migrations: docker-compose run --rm web bundle exec rails db:migrate
  6. If you use Elasticsearch or OpenSearch, rebuild the account search index with docker-compose run --rm web bin/tootctl search deploy --only=accounts

Update steps from 4.3.0-beta.1, 4.3.0-beta.2 or 4.3.0-rc.1

The following instructions are for updating from 4.3.0-beta.1, 4.3.0-beta.2 or 4.3.0-rc.1, see the section above if you are updating from an older version.

Non-docker

Tip

The charlock_holmes gem may fail to build on some systems with recent versions of gcc.
If you run into such an issue, try BUNDLE_BUILD__CHARLOCK_HOLMES="--with-cxxflags=-std=c++17" bundle install.

  1. If you are using rbenv, update the list of available versions and install the proper Ruby version by doing RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install in the Mastodon install directory (e.g. /home/mastodon/live)
  2. Install dependencies with bundle install and yarn install --immutable
  3. Precompile the assets: RAILS_ENV=production bundle exec rails assets:precompile
  4. Run the pre-deployment database migrations by specifying the SKIP_POST_DEPLOYMENT_MIGRATIONS=true environment variable: SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
  5. Restart all Mastodon processes. If you are updating directly from a Mastodon version earlier than 4.2.0, see the “Cookies and rolling updates” section.
  6. Run the post-deployment database migrations: RAILS_ENV=production bundle exec rails db:migrate

When using docker

  1. Run the pre-deployment database migrations by specifying the SKIP_POST_DEPLOYMENT_MIGRATIONS=true environment variable: docker-compose run --rm -e SKIP_POST_DEPLOYMENT_MIGRATIONS=true web bundle exec rails db:migrate
  2. Restart all Mastodon processes. If you are updating directly from a Mastodon version earlier than 4.2.0, see the “Cookies and rolling updates” section.
  3. Run the post-deployment database migrations: docker-compose run --rm web bundle exec rails db:migrate

Contributors

mjankowski, flavorjones, and 63 other contributors
Assets 2
Loading