khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-03 02:09:45 +07:00
Code Issues Packages Projects Releases Wiki Activity

fix(admin): Various Upgrade doc refinements

Browse Source 
Signed-off-by: Josh Richards <josh.t.richards@gmail.com>
This commit is contained in:
Josh Richards
2024-07-15 16:02:00 -04:00
parent fe8be76e22
commit 099c47da94
3 changed files with 94 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
admin_manual/maintenance/manual_upgrade.rst
View File

@@ -2,10 +2,26 @@
Upgrade manually
================
.. seealso::
Overview
--------
If you upgrade from a previous major version please see :ref:`critical changes<critical-changes>`
first.
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

43
admin_manual/maintenance/update.rst
View File

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

52
admin_manual/maintenance/upgrade.rst
View File

@@ -2,25 +2,43 @@
How to upgrade
==============
There are three ways to upgrade your Nextcloud server:
Overview
--------
* 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.
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).
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.
There are two ways to upgrade an Archive based Nextcloud Server deployment:
**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.
* 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.