Skip to main content

Upgrading to a new version

The DES image follows semantic versioning. This means that a new minor version is always deployable without doing any changes to your infrastructure or dependencies to DES, such as

  • The runtime environment (environment variables, volume mounts, etc.)
  • Backend API Clients
  • Banking applications / SDKs
  • etc.

Major versions on the other hand might come with change requirements to such dependencies. In those cases there will always be a preparatory minor release first, allowing you to introduce those required changes in a backwards-compatible way. This makes it possible to upgrade to a new major version without maintenance windows or downtime.

That said, minor versions might come with two different pre-requisites before they can be deployed:

  • The release contains database migrations which must be applied before the Web server or Background worker can be upgraded.
  • A previous (minor) release must be deployed first.

Migrating the DES database​

Before deploying a new version of DES to your Web server and Background worker, it is sometimes necessary to apply a set of required database migrations. The migrations are included in the release itself and can be applied by spinning up the new version of the image as a one-time task job or task, running the command ./docker/self-hosted/db-upgrade.sh.

Releases of DES which require migrations before they can be deployed are marked as such in the Changelog by a ❗️ Requires Migration tag. The migrations are idempotent and safe to run any number of times, even if there are no pending migrations to apply. Therefore our recommendation is in fact to always run them before deploying a new release of DES - whether marked as required or not.

NOTE: The ./docker/self-hosted/db-upgrade.sh command is not safe to be run by multiple processes at a time though, but should always be synchronized to a single workload at a time.

Mandatory releases​

Most of the time, it's possible to skip ahead multiple minor versions at a time. However, there are times when a previous release must be deployed before a later one can be safely deployed. In these cases, the pre-requisite release is marked as ❗️ Mandatory in the Changelog, and any upcoming release depending on it will say so in its operations instructions.

For example, let's say that you are on version 1.2.3 and want to skip to v1.4.0. Now it might be the case that "v1.3.0" is marked as "mandatory", and v1.4.0 says "Depends on 1.3.0". In this case, you must first (run any migrations and) deploy v1.3.0 before continuing to v1.4.0.