Upgrading Prosody

Overview

When the time comes to upgrade Prosody, don’t worry! This is usually very straightforward.

Before you upgrade

Check your config

Before upgrading, we recommend that you check your configuration for any problems - especially deprecated options, as these may have been removed entirely in the new release.

Run:

prosodyctl check config

Remove/update any deprecated options that it warns you about, and when it is happy you can proceed with installing the new Prosody version.

Backups

We also strongly recommend that you have regular backups of Prosody and its configuration, so you can easily restore it if anything goes wrong.

Check release notes

When we make important changes, we will always highlight these in the release notes of our first release in a series (these are releases where the version number ends with .0). Links to all release notes can be found on our Prosody releases page.

The release notes will tell you if there is anything to be aware of when upgrading, or common issues you may encounter.

If all looks good, you can now proceed with the upgrade!

Upgrading with a package manager

If you installed Prosody via a package manager (recommended!) such as apt on Debian/Ubuntu, it may prompt you when the configuration in our package changes - something we generally only do between major releases.

This prompt can vary, but usually looks something like:

Setting up prosody (13.0.0) ...

Configuration file '/etc/prosody/prosody.cfg.lua'
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
The default action is to keep your current version.
*** prosody (Y/I/N/O/D/Z) [default=N] ?

We recommend that you always keep your existing configuration file when upgrading. Each Prosody release should continue to work with a configuration file from the previous release, although it may generate warnings and some functionality may be limited.

After upgrading

After you have installed the new version of Prosody, check your configuration again for any newly recommended changes:

prosodyctl check config

Fix any problems, and generally you will want to restart Prosody one last time to apply them.

Controlled upgrades using nightly packages

Our package repository contains packages for each of our major branches, e.g. prosody-13.0. Once a branch is released it is considered stable, and will only receive bug fixes and no major changes.

Using these packages instead of the main ‘prosody’ package (which always follows the latest release) allows you to decide when you want to upgrade from one branch to the next.

If you decide to use the ‘prosody’ package from our repository, you may receive a new release as part of a normal ‘apt upgrade’ for example, and you may not be expecting it.