Platform Upgrades & What’s New

Here you find information about changes compared to the previous platform version, what to consider and where to take action before upgrading.

Note

Before upgrading a machine, please read the General upgrade remarks and Significant breaking changes. Contact our support for upgrade assistance.

Overview

Why upgrade? Security

Upgrading to the latest platform version as soon as possible is important to get all security package updates and other security-related improvements provided by NixOS (our “upstream” distribution we build on).

We do back-ports for critical security issues but this may take longer in some cases and less important security fixes will not be back-ported most of the time.

NixOS provides regular security updates for about one month after the release. Upstream support for 24.05 ended on 2024-12-31.

New platform features are always developed for the current stable platform version and only critical bug fixes are back-ported to older versions.

How to upgrade?

To upgrade your machines, the Environment to one of the fc-24.11-… values.
This can be done either via our customer portal, or by setting the platform version using the API.

General upgrade remarks

Our goal is to make upgrades as smooth as possible without manual intervention but sometimes incompatible configuration has to be fixed before starting an upgrade.

Here are some remarks to make sure that an upgrade will run successfully:

Isolate application deployments

As a general advice: reduce platform dependencies of your application deployment by using Nix-managed service user environments as described in User Package Management or other forms of dependency isolation like containers.

Upgrade staging first

Upgrades should always be checked in a staging environment first. We usually upgrade customer staging machines from our side as soon as the new platform version is ready for general testing. This is announced via our Flying Circus Statuspage where you can also subscribe to updates.

Upgrade to the next platform version

We recommend upgrading platform versions one at a time without skipping versions. Here we assume that you are upgrading from the 24.05 platform.

Direct upgrades from older versions are possible in principle, but we cannot reliably test all combinations for all roles and custom configuration also plays a role here. Usually, problems that occur when skipping versions are only temporary, like service failures that go away with the next system rebuild or a system/service restart.

Check free disk space

About 8-10 GiB should be available on disk before starting an upgrade to avoid triggering a low-disk alarm.

Usually, upgrades have an on-disk size of about 3-6 GiB which may be higher in certain configurations. We keep old system versions and let the Nix garbage collection clean them up, so the additional space will be used for at least 3 days.

Consider performance impact while upgrading

Upgrading may take some time, depending on the number of activated roles and disk speed. For production machines, upgrades are usually done in a maintenance window to reduce impact on regular operations. A VM may have degraded performance for some minutes when packages are being downloaded and built.

With NixOS, the switch to the new system happens after a successful system build so most services are unavailable at the same time and only for a small time-window.

Significant breaking changes

Matomo

This platform release removes support for version 4 of the Matomo web analytics tool. Existing installations will be upgraded to version 5.

This update is irreversable without manual admin interventions. For more details and upgrade instructions when still on the 24.05 platform, consult the upgrade documentation.

Installations that already upgraded to Matomo 5 during the 24.05 NixOS platform may remove services.matomo.package = pkgs.matomo_5; from their custom NixOS config after upgrading, this is the default now.

Webgateway (Nginx)

The nginx main process is running as user nginx by default since NixOS 22.11. The option services.nginx.masterUser to still run the main process as root has been removed in this platform version.

Configuring nginx via structured JSON config files in /etc/local/nginx/*.json has been removed. Affected machines already showed a NixOS warning in platform version 24.05. Nginx vhost configuration needs to be migrated to Structured Nix Configuration. As JSON config supports the same options as Nix config, converting from JSON to Nix is basically just a syntax change. Consult the examples in the role documentation or the option search for details.

In the next platform version, we plan to deprecate our custom option set flyingcircus.services.nginx in favour of the very similar NixOS upstream services.nginx options.
Consequentially, prefer using services.nginx options when migrating the JSON config if possible.

Percona/ MySQL

The release schema of Percona versions changed yet again. Percona will only create releases based on Oracle MySQL LTS releases anymore. Percona version 8.0 is still a supported LTS release and the one we recommend right now. The most current LTS release 8.4 is not supported from the start of the NixOS 24.11 release cycle, but will be introduced very soon in one of the regular releases.

The versions 8.1, 8.2, and 8.3 have been removed in this platform release. Users relying on these versions must not downgrade to Percona 8.0, but can upgrade to Üercona 8.4 once that is available in our platform.

Postgresql

The postgresql12 role has been dropped. The oldest supported PostgreSQL release is now 13. Upgrading PostgreSQL to at least version 13 needs to be done ahead of the platform upgrade, our fc-postgresql tool can help with that.

postgresql.service has enabled several hardening options by default now. Our platform role was adapted to be able to deal with this, but if your application relies on direct access to postgresql data directories, hardening options might need to be adjusted.

K3S

k3s-1.30.x is the default k3s version in this release.

Clusters that were created on the NixOS 24.05 platform already use that version. Clusters created at an earlier release might still be using an older k3s version, please verify that they are upgraded to k3s-1.30.x before upgrading to NixOS 24.11.

k3s nodes are only allowed to be updated ins steps of one minor version at a time. The Kubernetes control plane with the k3s-server role needs to be updated before the cluster’s worker nodes with the k3s-agent role are updated.

Contact support of you need help with updating your k3s cluster, or if you still need to use another specific k3s version for your cluster.

Slurm

This release contains a major version upgrade of Slurm from 23.11.x.x (NixOS 24.05) to 24.05.x.x. Nodes of a cluster need to be upgraded in a particular order, please consult the upgrade instructions of the role for details.

Docker

The default docker version is updated from 24 to 27. Some of the major changes are:

  • The devicemapper storage driver is not supported anymore. See Docker Storage Driver for background information and instructions on how to migrate your existing containers before upgrading.

  • docker-27 finally supports IPv6 networking by default. While this enables more modern networking setups, please ensure that your service security does not rely on the implicit assumption that containers have no IPv6 networking.

  • Read-only bind mounts are recursively read-only by default since docker-25.

Other notable changes

  • New supported PHP version: PHP 8.4

  • All Oracle JDKs and JREs were dropped due to being unmaintained and heavily insecure. OpenJDK provides compatible replacements for JDKs and JREs.

  • gradle_6 was removed due to being unsupported upstream

  • While openssl was updated from 3.0.x to 3.3.x, the openssl_3 package name continues to point to the 3.0.x series

  • For more details, see the release notes of NixOS 24.11.

Significant package updates

as of 2025-01-31

  • awscli: 1.32 -> 1.34

  • awscli2: 2.15 -> 2.19

  • binutils: 2.41 -> 2.43

  • calibre: 7.10 -> 7.21

  • clamav: 1.3 -> 1.4

  • cmake: 3.29 -> 3.30

  • curl: 8.7 -> 8.11

  • docker: 24.0 -> 27.3 (other versions available under alias)

  • ffmpeg: 6.1 -> 7.1

  • gcc: 13.2 -> 13.3

  • git: 2.44 -> 2.47

  • gitlab: 17.6 -> 17.7

  • glibc: 2.39 -> 2.40

  • go: 1.22 -> 1.23 (other versions available under alias)

  • grafana: 10.4 -> 11.3

  • haproxy: 2.9 -> 3.0

  • k3s: see above

  • keycloak: 25.0 -> 26.1

  • libressl: 3.9 -> 4.0

  • libtiff: 4.6 -> 4.7

  • libxml2: 2.12 -> 2.13

  • linux: 5.15 -> 6.6

  • mastodon: 4.2 -> 4.3

  • mongodb: 6.0 -> 7.0 (not managed by platform role)

  • nix: 2.18 -> 2.24

  • opensearch: 2.14 -> 2.17

  • openssh: 9.7p1 -> 9.9p1

  • openssl: 3.0 -> 3.3

  • phpPackages.composer: 2.7 -> 2.8

  • podman: 5.0 -> 5.2

  • python3: 3.11 -> 3.12 (other versions available under alias)

  • python3Packages.boto3: 1.34 -> 1.35

  • python3Packages.pillow: 10.3 -> 11.0

  • rabbitmq-server: 3.12 -> 4.0

  • rclone: 1.66 -> 1.68

  • rsync: 3.3 -> 3.4

  • ruby: 3.1 -> 3.3 (other versions available under alias)

  • systemd: 255 -> 256

  • varnish: 7.4 -> 7.5

  • wget: 1.21 -> 1.25