diff --git a/admin_manual/maintenance/manual_upgrade.rst b/admin_manual/maintenance/manual_upgrade.rst index 44aac2d497e..88313f979b9 100644 --- a/admin_manual/maintenance/manual_upgrade.rst +++ b/admin_manual/maintenance/manual_upgrade.rst @@ -2,10 +2,26 @@ Upgrade manually ================ -.. seealso:: - - If you upgrade from a previous major version please see :ref:`critical changes` - first. +Overview +-------- + +In some environments using the Built-in Updater in Web mode is not reliable (such as due to web server +timeouts) and running it in command-line mode is not an option (such as in some shared hosting environments). +In these cases a manual upgrade may be the best approach. + +A manual upgrade consists of downloading and unpacking the Nextcloud Archive file either to your PC or host. Then +deleting your existing Nextcloud Server installation files and folders, **except ``data/`` and ``config/``**, on +your host. Then moving the new Nextcloud Server installation files into the appropriate place on your host, +again preserving your existing ``data/`` and ``config/`` files. And doing a few other housekeeping items, such as +making sure your installed apps are transferred into the new installation and adjusting permissions. That may sound +like a lot, but detailed instructions are below. + +.. important:: + Before upgrading, especially between major versions (e.g. v27.y.z -> v28.y.z) please review + :ref:`critical changes` first. These are highlights of changes that may be required + in your environment to accomodate changes in Nextcloud Server. These notes are periodically revised as + needed so it is a good idea to revisit them even when proceeding with minor and maintenance upgrades just + in case. .. warning:: @@ -14,6 +30,10 @@ Upgrade manually following the standard :doc:`upgrade requirements <./upgrade>` (such as upgrading to the latest maintenance release *before* upgrading to a new major release). + +Step-by-Step Manual Upgrade +--------------------------- + .. important:: Always start by making a fresh backup and disabling all 3rd party apps. 1. Back up your existing Nextcloud Server database, data directory, and diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index c1aa2384d39..70f3a7d857b 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -15,18 +15,21 @@ and data, and it automates updating you have paid support or ask for help in the Nextcloud forums to see if your issue can be resolved without downgrading. -You should maintain regular backups (see :doc:`backup`), and make a backup -before every update. The built-in updater does not backup your database or data -directory. +.. danger:: + You should maintain regular backups (see :doc:`backup`), and make a backup + before every update. The built-in updater does not backup your database or data + directory. What does the updater do? ------------------------- .. note:: - The updater itself only replaces the existing files with the ones from the - version it updates to. The migration steps needs to be executed afterwards. - The command line mode provides a way to do this right after the code was - successfully replaced. + The built-in updater itself only replaces the existing files with the ones from the + version it updates to. The migration phase, which upgrades your database and apps, + needs to be executed afterwards. In command line mode, the updater offers to trigger this + for you right after the code was successfully replaced by running ``occ upgrade`` for you. + In web mode, the updater finishes and then offers to send you back to your instance's main + URL to trigger the migration phase's web UI. The built-in updater performs these operations: @@ -230,3 +233,29 @@ To execute this, run the command with the ``--no-interaction`` option. (i.e. .. image:: images/updater-cli-8-no-interaction.png :class: terminal-image +Troubleshooting +--------------- + +* The built-in updater logs all of its actions to a dedicated log file called + ``updater.log`` located in your configured ``datadirectory`` + (e.g. ``/var/www/html/data/updater.log``). This file can be helpful in isolating + where things are failing. It will also be needed if you reach out for assistance + on the community help forum (https://help.nextcloud.com). + +* If you are having problems using the Updater in web-mode, you should try using + command-line mode (if it's an option in your environment). Command-line avoids + issues with web server timeouts, which can be problematic since sometimes the + Updater can take a long time to complete certain steps. + +* If the problem seems to be during the backup step, you can try disabling the + backups the updater automatically creates of the installation files. Keep in + mind these backups do **not** include your data (which you are already hopefully + doing). The backup step can only be disabled while in command-line mode. Append + the option ``--no-backup`` to the ``updater.phar`` command. + +* If you accidentally say no when the command-line mode of the updater asks if you'd + like to run ``occ upgrade``, you can safely execute ``occ upgrade`` manually or + simply visit the URL of your instance to complete the database migrations and app + upgrade phase. + +* Reach out to the community help forum for assistance (https://help.nextcloud.com) diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst index aa209a93375..786c5716a1c 100644 --- a/admin_manual/maintenance/upgrade.rst +++ b/admin_manual/maintenance/upgrade.rst @@ -2,25 +2,43 @@ How to upgrade ============== -There are three ways to upgrade your Nextcloud server: - -* With the :doc:`Updater `. -* :doc:`Manually upgrading ` with the Nextcloud ``.tar`` archive - from our `Download page `_. -* :doc:`Upgrading ` via the snap packages. -* Manually upgrading is also an option for users on shared hosting; download - and unpack the Nextcloud tarball to your PC. Delete your existing Nextcloud - files, except ``data/`` and ``config/`` files, on your hosting account. Then - transfer the new Nextcloud files to your hosting account, again - preserving your existing ``data/`` and ``config/`` files. - -When an update is available for your Nextcloud server, you will see a -notification at the top of your Nextcloud Web interface. When you click the -notification it brings you here, to this page. - -**It is best to keep your Nextcloud server upgraded regularly**, and to install -all point releases and major releases. -Major releases are 18, 19 or 20. Point releases are intermediate releases for each major release. For example 18.0.4 and 19.0.2 are point releases. +Overview +-------- + +The approach used to upgrade your Nextcloud Server depends on your installation type. This +manual mainly focuses on the methods that apply to an Archive based installation. If you installed +using Snap, Docker, a pre-built VM, or a package management tool then refer to the installation +and update instructions for that installation method for the most accurate upgrading inststructions +(generally located at the distribution point for the install method you chose). + +There are two ways to upgrade an Archive based Nextcloud Server deployment: + +* With the :doc:`Built-in Updater ` (via the web or command-line interfaces). +* :doc:`Manually upgrading ` (using a downloaded Archive file) + +The Built-in Updater, in either Web or command-line mode, is the easiest choice for most environments. +However some environments require the manual approach. Both approaches are covered fully here. + +.. important:: + Before upgrading, especially between major versions (e.g. v27.y.z -> v28.y.z) please review + :ref:`critical changes` first. These are highlights of changes that may be required + in your environment to accomodate changes in Nextcloud Server. These notes are periodically revised as + needed so it is also a good idea to revisit them periodically, such as when proceeding with maintenance + upgrades. + +When an update is available for your Nextcloud server, by default you will receive +a notification. You can also check for available updates by visiting the Update section under +**Administration settings->Overview** in the Web UI. + +.. note:: + It is best to keep your Nextcloud server upgraded regularly. This means installing all maintenance/point releases + and upgrading to new major releases before your current one reaches :doc:`end-of-life` status. + Examples of major releases are 27, 28, or 29. Maintenance releases are intermediate releases for each + major release that address critical functionality or security bugs. For example 28.0.4 and 29.0.2 are maintenance + releases. + +Approaching Upgrades +-------------------- Nextcloud must be upgraded step by step: * Before you can upgrade to the next major release, Nextcloud upgrades to the latest point release. @@ -131,4 +149,4 @@ Those include for example:: $ sudo -u www-data php occ db:add-missing-indices $ sudo -u www-data php occ db:add-missing-primary-keys -You can use the ``--dry-run`` option to output the SQL queries instead of executing them. \ No newline at end of file +You can use the ``--dry-run`` option to output the SQL queries instead of executing them.