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.
tar -xjf nextcloud-n.n.n.tar.bz2
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.
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:
- 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:
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.