Merge pull request #12041 from nextcloud/backport/12021/stable29

[stable29] fix(admin): Various Upgrade doc refinements

Author: joshtrichards

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<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<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 

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)

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 <update>`.
-* :doc:`Manually upgrading <manual_upgrade>` with the Nextcloud ``.tar`` archive
-  from our `Download page <https://nextcloud.com/install/>`_.
-* :doc:`Upgrading <package_upgrade>` 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 <update>` (via the web or command-line interfaces).
+* :doc:`Manually upgrading <manual_upgrade>` (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<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</release_schedule>` 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.
+You can use the ``--dry-run`` option to output the SQL queries instead of executing them.