The updater app to keep your Nextcloud up-to-date
AGPL-3.0 License
The built-in Updater makes it easier to keep your Nextcloud Server installation up-to-date. In many cases it can be used in place of the manual update process.
The Updater can be accessed via the Web UI as well as the command line. It may be used both to update to the latest patch level (i.e. security/bug fixes) as well as to update to a completely new major release (i.e. new features/functionality).
createBackup
step, which is not intended to backup user data, currently can slow down the larger the datadirectory
gets (nextcloud/updater#507)deleteOldFiles
step, which does not actually touch user data, currently can slow down the larger the datadirectory
gets (nextcloud/updater#397)*.config.php
files are currently not supported / ignored (nextcloud/updater#384)[!NOTE] The built-in Updater is primarily applicable to manual/Archive (aka: "tarball / zip") installations. Most other installation methods (such as Docker images and Snaps) utilize their own officially supported processes for keeping Nextcloud Server up-to-date. Please follow their respective documented approaches rather than trying to run the Updater yourself.
Note:
updatenotification
app is enabled.As a shipped/bundled app:
No special configuration parameters are generally required for the Updater. There are some optional parameters which may be of interest in some environments:
updatedirectory
upgrade.disable-web
upgrade.cli-upgrade-link
updater.secret
]updater.server.url
updater.release.channel
maintenance
There are also some which are set automatically and not generally meant to be manually adjusted:
The following are standard parameters already set in any functioning Server installation, but which the Updater requires:
datadirectory
]instanceid
]Other update related parameters:
Using the Updater via the Web UI is more convenient, but using it from the command line is more reliable.
[!WARNING] Please make a backup of your data and database and familiarize yourself with the restore process before proceeding with using the Updater.
Go to Administration settings. It can be reached in the Overview under the Update heading.
See Using the web based updater in the Nextcloud Administration Manual.
See Using the command line based updater
updater.phar
Parameters:
--no-backup Don't create a backup of the application code (note: the Updater's backup *never* backs up data or databases contents)
--no-upgrade Don't automatically run `occ upgrade` when the Updater finishes (note: `occ upgrade` is required after Updater updates the application code in order to push out any database changes in the newly deployed version of Nextcloud)
Keeping Nextcloud Server up-to-date, at a high level, consists of three things:
The Updater app handles step #1 (see What does the updater do?) and prepares the environment for steps #2 and #3 (which are handled by occ upgrade
after the Updater successfully completes).
The Updater app needs to function while the Nextcloud Server is offline for code updates. It is therefore designed to operate as independently as possible from the rest of Server. This permits Server to be updated safely and the Updater to proceed without interruption during code swaps. The trade-off is that none of the typical Nextcloud classes/APIs are available to serve the needs of the Updater. The Updater, fortunately, has a relatively narrowly defined mission and set of needs.
/updater/index.php
(Web mode) or /updater/updater.phar
(Command line mode), which are.step
files/foldersSome historical more in-depth context can be found in nextcloud/updater#1 and nextcloud/updater#2.
/updater/updater.phar
(CLI Updater)/updater/index.php
(Web Updater)occ upgrade
(Database Upgrader)occ upgrade
trigger/monitorupdatenotification
app which provides the Update overvew under Administration settings and handles notifying admins of the availability of updatesupdatenotification
is disabled and does not provide an Overview screen; currently generates an indefinite "nag")Since there are multiple ways of triggering and using the Updater as well as the later database upgrades and app updates, it is useful to have an overview of the different work flows. This is particularly useful if you're doing development related to the Nextcloud Server update/upgrade process. It also further shows how steps 1-3 above are coupled together.
Consists of:
occ upgrade
from the command lineThe full procedure for keeping Nextcloud Server up-to-date manually is documented in the Nextcloud Admin Manual.
Consists of:
/updater/updater.phar
from the command lineocc upgrade
from the command lineConsists of:
/updater/updater.phar
from the command lineocc upgrade
from the Web UI (this is the default behavior after a successful Updater run if you do not opt to let updater.phar
trigger the database upgrades and app updates at the end of its run)Consists of:
/updater/index.php
via Administration settings->Overview Update section.occ upgrade
from the command lineConsists of:
/updater/index.php
via Administration settings->Overview Update section.occ upgrade
from the Web UI (this is the default behavior after a successful Updater run if you opt to let the Web Updater trigger the database upgrades and app updates at the end of its run)Implementation:
/updater/index.php
)occ upgrade
or to leave maintenance mode on so that the user can complete those from the command line by executing occ upgrade
on their own)Described here are both relevant aspects of the Updater itself as well as surrounding components that are integrated into Server directly.
For each mode the Updater supports - Web and command line - a dedicated artifact is generated. However, all common operations are located in shared code. Since the code is not shared in all cases at runtime, it's important to understand where various changes should go during development so that they end up in the appropriate places at build or check-in time.
Changes should be made to the following places in the updater
repo:
/Makefile
make updater.phar
make index.php
/lib/LogException.php
/lib/RecursiveDirectoryIteratorWithoutDate.php
/lib/UpdateException.php
/lib/Updater.php
<-- core of the Updater functionality for both Web and CLI modes is implemented here/index.web.php
/Makefile
make index.php
/updater.php
/buildVersionFile.php
/lib/CommandApplication.php
/lib/UpdateCommand.php
/Makefile
make updater.phar
Keep in mind that for the update/upgrade process there are some additional components that aren't part of the Updater app (nor necessarily part of
occ upgrade
itself):
occ upgrade
command maintained as part of server
:
occ upgrade
directly from the command-lineInstall box: https://github.com/box-project/box/blob/main/doc/installation.md#composer
If you want to run the tests locally, you'll need to run them in an environment that has Nextcloud's required PHP modules installed. The various test scenarios are all available via the make test*
(see Makefile for specifics).
/updater.phar
/index.php
/updater.phar
/index.php
Plus whatever has been changed in the implementation in:
/lib/*
/index.web.php
/updater.php
Used during the build process but not checked in:
/lib/Version.php
If it keeps failing on your PR, confirm your local version of composer
is the same version in-use in the workflow runner. You can check the details of the test run and find the version currently being used (and therefore required locally) under "Setup Tools". (Hint: distro versions are typically too outdated. Remove that version and see https://getcomposer.org/download/ to install your own version).
(to be filled in)
(to be filled in)
(to be filled in)
updater.log
which is located in the configured datadirectory
for the instance.nextcloud.log
)updater.log
If the built-in Updater does not function reliably for your environment, the old reliable (albeit admittedly tedious) manual update process may be your best alternative. This was the primary way of keeping Nextcloud Server up-to-date before the automated Updater was developed. In addition, if Updater does not work in your environment, report the details of your situation to https://github.com/nextcloud/updater/issues so that consideration can be given to adapting Updater to a wider variety of environments.
occ upgrade
The occ upgrade
command runs the database migrations which adapt your existing database to the updated version Nextcloud Server that is deployed by the Updater (or via a manual update).
Despite the confusing naming - which makes sense technically, but in hindsight may not have been the best to avoid confusion - the Updater must run (and completely successfully) before occ upgrade
will have anything to do.
[!TIP] Since bug reports are not for technical support, you may not receive a personalized or timely response. If you suspect you may have encountered a previously unknown bug, please try to troubleshoot it in the Help Forum first to confirm or to uncover workarounds.