Manual upgrade to Nextcloud version 20, 21 and 22

Update 2021-04-12: Nextcloud upgrade tested also from version 20 to version 21.
Update 2021-07-10: upgrade to version 22 was a challenge, but problems were solved. See below.

Our Nextcloud system is small but it is a vital resource for us. We have always updated the software as soon as new major and minor versions have been released. So far, updates have been easy. The Updater that runs in browser has done all the work. Unfortunately, this is not the case anymore. Upgrade from version 19.0.4 to 20.0.1 failed completely. So, we decided to dive into the manual update process. Here is what we learned: instructions for updating Nextcloud using the Linux command line.

Depending on your version of PHP, or web server software your upgrade may behave slightly differently. Our Nextcloud is running on Debian 10, Apache 2.4, Mysql/Mariadb 10.3, and PHP 7.3. These instructions are based on that system configuration.

Step by step upgrade guide for Nextcloud (command line)

Backup the Nextcloud database.
We also backed up the data and config directories located under the main Nextcloud directory.

Download the release of Nextcloud you want to upgrade.

Turn Maintenance mode on for the Nextcloud server. www-data is the user name Apache server uses, other web servers and Linux distributions may have other names, so change the name accordingly.
sudo -u www-data php occ maintenance:mode --on

Tip: go to the directory where occ command is – it should be in the main Nextcloud directory. If occ refuses to run, try:
sudo -u www-data php ./occ maintenance:mode --on

Unzip the zip file or unpack the tar package into the current Nextcloud directory. Note: the previous version is replaced with the new one – you should save the old version first if you want to keep it.
unzip nextcloud-n.n.n.zip
or
tar -xjf nextcloud-n.n.n.tar.bz2

If you copy the new version over the old from your PC using a FTP program, ensure all the directories and files under your nextcloud main directory are owned by the web server user (for Apache2, it is www-data):

chown -R www-data *

Run the upgrade program:
sudo -u www-data php occ upgrade

If the upgrade was successful, turn off Maintenance mode:
sudo -u www-data php occ maintenance:mode --off

Multiple steps longer, more detailed upgrade guide with a few troubleshooting tips is available in the Admin manual.

Upgrade from version 20 to 21

Upgrade from version 20.0.8 to version 21.0.1 worked without problems in our system. New system warnings appeared after the upgrade, so it is important to view the Settings – Administration/Overview for information.

Upgrade from Nextcloud 21 to 22

A word of caution: after running Nextcloud 22 for two weeks, it has become painfully clear that version 22.0.0 is not ready for daily production use. The upgrade has its problems, but risks with apps that don’t work with version 22.0 are more serious. For instance, incompatibility with two-factor authentication may prevent login to the system.

On our system, the upgrade from Nextcloud 21 to version 22 was a time-consuming project because of two nasty problems. The manual upgrade process went through without any problems. The log didn’t include error or warning messages.

When I tried to open Nextcloud in a web browser, it displayed a message that told me to run Update. There were no other choices, so I clicked the Update button. The Update ran, and again, the log was clean: no errors. Then, the same Update button appeared again, requesting me to run Update. It was an endless loop.

Where and how to start problem-solving without any clues? The Update button said it wants to upgrade files_sharing app and disable twofactor_nextcloud_notification app (although the log indicated they had been done). As I browsed the apps directory, I noticed new directories and files. They were not owned by the web server user that is www-data for Apache2. The command:

chown -R www-data *

Assigns all files and directories recursively to www-data. But still, the web user interface insisted on updating the software, referring to files_sharing app. Perhaps there is a way to update the app on the command line? Yes, there is. Update didn’t work, but disabling the app is possible as well:

sudo -u www-data php occ app:disable files_sharing 

That was it! File sharing feature is now disabled, but the version 22 works.

Verify the upgraded system

Especially, upgrading a major version can cause side-effects. Nextcloud 20 seems to have a number of them, so take a little time to check a few things after the update.

Go to the admin panel (Settings – Administration/Overview). If you have the following error message:

• “Some app directories are owned by a different user than the web server one. This may be the case if apps have been installed manually. Check the permissions of the following app directories:
  nextcloud/apps/dashboard
  nextcloud/apps/user_status
• The solution: change the owner of the directory and its files. Here again, www-data is the user name of the web server:
  chown -R www-data dashboard
chown -R www-data user_status

Admin panel (Settings, Administration/Overview) may list warnings that refer to database fields, like:

occ db:convert-filecache-bigint
occ db:add-missing-indices
occ db:add-missing-primary-keys

The complete command to run is:

sudo -u www-data php ./occ db:convert-filecache-bigint
sudo -u www-data php ./occ db:add-missing-indices
sudo -u www-data occ db:add-missing-primary-keys

Another error message:

• “Some files have not passed the integrity check. Further information on how to resolve this issue can be found in the documentation. (List of invalid files… / Rescan…)”
• In our case, the problem was apps installed during the previous version of Nextcloud. The integrity check displayed them as Extra Files.
• The solution: We did nothing because the apps will be installed when they are available for version 20.

When you check the apps available in your Nextcloud installation, you may find out that many apps have been disabled in the new version.

• The solution: There is no other choice than to wait for updates for the apps.

Browser based Updater failed with version 20

We started the upgrade to Nextcloud 20 in the browser based updater program. It failed. It stopped in an ambiguous error message that hinted at problems in the integrity of the package.

A few attempts later, the Updater was stuck in Maintenance mode, and the entire system was unusable.

A number of similar error descriptions on the community forum indicated that this wasn’t a trivial problem to solve. And it wasn’t. After we had spent too much time on it, we decided to try the command line update – and it worked like a charm.