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

Merge pull request #1921 from owncloud/upgrade

Browse Source 
corrections and updates to upgrading docs
This commit is contained in:
Carla Schroder
2015-11-25 13:04:03 -08:00
parent d8381d396e 982342676d
commit f1c5bdcbed
8 changed files with 334 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
admin_manual/maintenance/images/2-updates.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
admin_manual/maintenance/images/upgrade-2.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 46 KiB

After

Width:  |  Height:  |  Size: 23 KiB

BIN
admin_manual/maintenance/images/upgrade-3.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

BIN
admin_manual/maintenance/images/upgrade-notifier.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.8 KiB

2
admin_manual/maintenance/index.rst
View File

@@ -8,6 +8,8 @@ Maintenance
enable_maintenance
backup
upgrade
package_upgrade
manual_upgrade
update
restore
migrating

125
admin_manual/maintenance/manual_upgrade.rst Normal file
View File

@@ -0,0 +1,125 @@
=======================
Manual ownCloud Upgrade
=======================
Always start by making a fresh backup & disabling all 3rd party apps.
Put your server in maintenance mode. This prevents new logins, locks the
sessions of logged-in users, and displays a status screen so users know what is
happening. There are two ways to do this, and the preferred method is to use the
:doc:`occ command <../configuration_server/occ_command>`, which you must run as
your HTTP user. This example is for Ubuntu Linux::
sudo -u www-data php occ maintenance:mode --on
The other way is by entering your ``config.php`` file and changing
``'maintenance' => false,`` to ``'maintenance' => true,``.
1. Back up your existing ownCloud Server database, data directory, and
``config.php`` file. (See :doc:`backup`.)
2. Download and unpack the latest ownCloud Server release (Archive file) from
`owncloud.org/install/`_ into an empty directory outside
of your current installation. For example, if your current ownCloud is
installed in ``/var/www/owncloud/`` you could create a new directory called
``/var/www/owncloud2/``
.. note:: Enterprise users must download their new ownCloud archives from
their accounts on `<https://customer.owncloud.com/owncloud/>`_
3. Stop your Web server.
4. Rename or move your current ownCloud directory (named ``owncloud/`` if
installed using defaults) to another location.
5. Unpack your new tarball::
tar xjf owncloud-latest.tar.bz2
6. This creates a new ``owncloud/`` directory populated with your new server
files. Copy this directory and its contents to the original location of your
old server, for example ``/var/www/``, so that once again you have
``/var/www/owncloud`` .
7. Copy and paste the ``config.php`` file from your old version of
ownCloud to your new ownCloud version.
8. If you keep your ``data/`` directory in your ``owncloud/`` directory, copy
it from your old version of ownCloud to the ``owncloud/`` directory of
your new ownCloud version. If you keep it outside of ``owncloud/`` then
you don't have to do anything with it, because its location is configured in
your original ``config.php``, and none of the upgrade steps touch it.
9. If you are using 3rd party applications, look in your new ``owncloud/apps/``
directory to see if they are there. If not, copy them from your old ``apps/``
directory to your new one. Make sure the directory permissions of your third
party application directories are the same as for the other ones.
10. Restart your Web server.
11. Now launch the upgrade from the command line using ``occ``, like this
example on CentOS Linux::
sudo -u apache php occ upgrade
12. The upgrade operation takes a few minutes to a few hours, depending on the
size of your installation. When it is finished you will see a success
message, or an error message that will tell where it went wrong.
Assuming your upgrade succeeded, disable the maintenance mode::
sudo -u www-data php occ maintenance:mode --off
Login and take a look at the bottom of your Admin page to
verify the version number. Check your other settings to make sure they're
correct. Go to the Apps page and review the core apps to make sure the right
ones are enabled. Re-enable your third-party apps. Then apply strong
permissions to your ownCloud directories (:ref:`strong_perms_label`).
Reverse Upgrade
---------------
If you need to reverse your upgrade, see :doc:`restore`.
Troubleshooting
---------------
When upgrading ownCloud and you are running MySQL or MariaDB with binary
logging
enabled, your upgrade may fail with these errors in your MySQL/MariaDB log::
An unhandled exception has been thrown:
exception 'PDOException' with message 'SQLSTATE[HY000]: General error: 1665
Cannot execute statement: impossible to write to binary log since
BINLOG_FORMAT = STATEMENT and at least one table uses a storage engine limited
to row-based logging. InnoDB is limited to row-logging when transaction
isolation level is READ COMMITTED or READ UNCOMMITTED.'
Please refer to :ref:`db-binlog-label` on how to correctly configure your
environment.
Occasionally, *files do not show up after a upgrade*. A rescan of the files can
help::
sudo -u www-data php console.php files:scan --all
See `the owncloud.org support page <http://owncloud.org/support>`_ for further
resources for both home and enterprise users.
Sometimes, ownCloud can get *stuck in a upgrade*. This is usually due to the
process taking too long and encountering a PHP time-out. Stop the upgrade
process this way::
sudo -u www-data php occ maintenance:mode --off
Then start the manual process::
sudo -u www-data php occ upgrade
If this does not work properly, try the repair function::
sudo -u www-data php occ maintenance:repair
.. _owncloud.org/install/:
https://owncloud.org/install/

159
admin_manual/maintenance/package_upgrade.rst Normal file
View File

@@ -0,0 +1,159 @@
==============================
Upgrade ownCloud From Packages
==============================
.. note:: Starting with ownCloud 8.2 the Linux package repositories have
changed, and **you must configure your system to use these new
repositories** to install or upgrade ownCloud 8.2+. The new repositories are
at our `Open Build Service`_.
Upgrade Quickstart
------------------
The core upgrade notifier tells you when a new ownCloud release is available.
If you click on it, it takes you to :doc:`upgrade`.
.. figure:: images/upgrade-notifier.png
:alt: The upgrade notifier, a yellow banner at the top of the ownCloud Web
interface.
The best method for keeping ownCloud current on Linux servers is by configuring
your system to use ownCloud's `Open Build Service`_ repository. Then stay
current by using your Linux package manager to install fresh ownCloud packages.
After installing upgraded packages you must run a few more steps to complete the
upgrade. These are the basic steps to upgrading ownCloud:
* :doc:`Disable <../installation/apps_management_installation>` all third-party
apps.
* Make a :doc:`fresh backup <backup>`.
* Install new packages from the ownCloud `Open Build Service`_.
* Take your ownCloud server out of :doc:`maintenance mode
<enable_maintenance>`.
* Run the :ref:`upgrade wizard <upgrade_wizard_label>` or
``occ upgrade`` (optionally disabling the :ref:`migration test
<migration_test_label>`).
* :ref:`apply strong permissions <strong_perms_label>` to your
ownCloud directories.
* Re-enable third-party apps.
Upgrading With Your Linux Package Manager
-----------------------------------------
Upgrading ownCloud from our `Open Build Service`_ repository is just like any
normal Linux upgrade. For example, on Debian or Ubuntu Linux this is the
standard system upgrade command::
apt-get update && apt-get upgrade
Or you can upgrade just ownCloud with this command::
apt-get update && apt-get install owncloud
On Fedora, CentOS, and Red Hat Linux use ``yum`` to see all available updates::
yum check-update
You can apply all available updates with this command::
yum update
Or update only ownCloud::
yum update owncloud
Your Linux package manager only downloads the current ownCloud packages. Then
your ownCloud server is immediately put into maintenance mode. You may not see
this until you refresh your ownCloud page.
.. figure:: images/upgrade-1.png
:scale: 75%
:alt: ownCloud status screen informing users that it is in maintenance mode.
*Click to enlarge*
To complete the upgrade take your server out of maintenance mode. You can do
this by changing ``'maintenance' => true,`` to ``'maintenance' => false,`` in
``config.php``, or use the :doc:`occ command
<../configuration_server/occ_command>`, like this example on Ubuntu::
sudo -u www-data php occ maintenance:mode --off
You must run ``occ`` as your HTTP user.
.. _upgrade_wizard_label:
Upgrade Wizard
--------------
The final step is to run the upgrade wizard to perform the final steps of
updating your apps and database. Refresh your ownCloud page and you will see a
screen with some warnings about backups and a **Start Update** button.
(Alternatively, you may use ``occ upgrade``, which is covered in the next
section.) Click the **Start Update** button:
.. figure:: images/upgrade-2.png
:scale: 75%
:alt: ownCloud upgrade wizard screen.
*Click to enlarge*
The wizard will put ownCloud back into maintenance mode, display a
status screen while the upgrade is running, and when it is completed take it
out of maintenance mode and return you to your ownCloud session.
.. figure:: images/upgrade-3.png
:scale: 75%
:alt: Upgrade wizard status screen.
*Click to enlarge*
occ Upgrade
-----------
If you have shell access it is better to **not** click the **Start Update**
button, but rather to use ``occ upgrade``. ``occ upgrade`` is more reliable,
especially on installations with large datasets and large numbers of users
because it avoids the risk of PHP timeouts. This example is for CentOS::
sudo -u apache php occ upgrade
ownCloud or one of the apps require upgrade - only a limited number of
commands are available
Set log level to debug - current level: 'Warning'
Turned on maintenance mode
Checking whether the database schema can be updated (this can take a long
time depending on the database size)
Checked database schema update
Checking updates of apps
Checked database schema update for apps
Updating database schema
Updated database
Update successful
Turned off maintenance mode
Reset log level to 'Warning'
Remember, you must run ``occ`` as your HTTP user. When it is completed refresh
your ownCloud Web page to return to your previous session.
.. _migration_test_label:
Migration Test
^^^^^^^^^^^^^^
ownCloud starts your upgrade by first running a simulation: it copies all
database tables to a temporary directory, and then performs the upgrade on
them to ensure that the upgrade will complete correctly. This can delay large
installations by several hours, so you can omit this step with the
``--skip-migration-test`` option, like this example on CentOS::
$ sudo -u apache php occ upgrade --skip-migration-test
Setting Strong Permissions
--------------------------
After upgrading, verify that your ownCloud directory permissions are set
according to :ref:`strong_perms_label`.
If the upgrade fails, then you must try a manual upgrade.
.. _Open Build Service:
https://download.owncloud.org/download/repositories/8.2/owncloud/

317
admin_manual/maintenance/upgrade.rst
View File

@@ -1,34 +1,29 @@
==============================
Upgrading Your ownCloud Server
==============================
===================================
How to Upgrade Your ownCloud Server
===================================
Starting with ownCloud 8.2 the Linux package repositories have changed, and
**you must configure your system to use these new repos**. The new repos are at
our `Open Build Service`_. Just follow the instructions for your Linux
distribution, and then install new ownCloud packages in the usual way with your
package manager.
There are three ways to upgrade your ownCloud server:
It is best to keep your ownCloud server upgraded regularly, and to install all
point releases and major releases without skipping any of them, as skipping
releases increases the risk of errors. Major releases are 8.0, 8.1, 8.2, and
9.0. Point releases are intermediate releases for each major release. For
example, 8.0.9 and 8.1.3 are point releases.
* Using your :doc:`Linux package manager <package_upgrade>` with our `Open
Build Service`_ repository. This is the recommended method.
* With the :doc:`Updater App <update>` (Server Edition only). Recommended for
shared hosters, and for users who want an easy way to track different
release channels. (It is not available and not supported on the Enterprise
edition.)
* :doc:`Manually upgrading <manual_upgrade>` with the ownCloud ``.tar`` archive
from `owncloud.org/install/`_.
* Enterprise Subscription customers will use their Enterprise software
repositories to maintain their ownCloud servers, rather than the Open Build
Service. Please see :doc:`../enterprise_installation/linux_installation` for
more information.
When an update is available for your ownCloud server, you will see a
notification at the top of your ownCloud Web interface. When you click the
notification it brings you here, to this page.
There are multiple ways to keep your ownCloud server upgraded: with the
:doc:`Updater App <update>` (Server Edition only), with your Linux package
manager, and by manually upgrading. In this chapter you will learn how to keep
your ownCloud installation current with your Linux package manager, and by
manually upgrading.
.. note:: Enterprise Subscription customers will use their Enterprise software
repositories to install ownCloud packages, rather
than the Open Build Service. Then follow the instructions on this page
for completing upgrades. Please see
:doc:`../enterprise_installation/linux_installation` for more information.
When you are upgrading to a major release, evaluate any third-party apps for
compatibility with the upgrade, and then disable them before upgrading. You may
re-enable them after the upgrade is completed.
**Upgrading is disruptive**. Your ownCloud server will be put into maintenance
mode, so your users will be locked out until the upgrade is completed. Large
installations may take several hours to complete the upgrade.
.. note:: **Downgrading is not supported** and risks corrupting your data! If
you want to revert to an older ownCloud version, make a new, fresh
@@ -36,255 +31,39 @@ re-enable them after the upgrade is completed.
file a support ticket (if you have paid support) or ask for help in the
ownCloud forums to see if your issue can be resolved without downgrading.
Upgrade Quickstart
------------------
Update Notifier and Updater App Are Not the Same
------------------------------------------------
The best method for keeping ownCloud on Linux servers current is by configuring
your system to use ownCloud's `Open Build Service`_ repository. Then stay
current by using your Linux package manager to install fresh ownCloud packages.
After installing upgraded packages you must run a few more steps to complete
the upgrade. These are the basic steps to upgrading ownCloud:
ownCloud has two update tools: the ownCloud core update notifier, and the
Updater app. Figure 1 shows what you see when the Updater app is enabled: both
the core notifier and the Updater app control panel are visible on your admin
page.
* :doc:`Disable <../installation/apps_management_installation>` all third-party
apps.
* Make a :doc:`fresh backup <backup>`.
* Install new packages from the ownCloud `Open Build Service`_.
* Take your ownCloud server out of :doc:`maintenance mode
<enable_maintenance>`.
* Run the :ref:`upgrade wizard <upgrade_wizard_label>` (optionally disabling
the :ref:`migration test <migration_test_label>`).
* Log in and :ref:`apply strong permissions <strong_perms_label>` to your
ownCloud directories.
* Re-enable third-party apps.
.. figure:: images/2-updates.png
:alt: Both update mechanisms displayed on Admin page.
*Figure 1: The top yellow banner is the update notifier, and the Updates
section is the Updater app.*
The core update notifier has only one function, and that is to display a
notification when a new ownCloud release is available. Then you decide which
upgrade method to use. When you maintain your ownCloud server via your Linux
package manager you should ensure that the Updater app is disabled.
Prerequisites
-------------
You should always maintain regular backups and make a fresh backup before every
upgrade.
You should always maintain :doc:`regular backups <backup>` and make a fresh
backup before every upgrade.
Then review any third-party apps you have installed for compatibility with the
new ownCloud release. Any apps that are not developed by ownCloud show a 3rd
party designation. **Install unsupported apps at your own risk**. Then, before
the upgrade, they must all be disabled. After the upgrade is complete and you
are sure they are compatible with the new ownCloud release you may re-enable
them.
**Upgrading is disruptive**. Your ownCloud server will be automatically put
into maintenance mode, so your users will be locked out until the upgrade is
completed. Large installations may take several hours to complete the upgrade.
Upgrading With Your Linux Package Manager
-----------------------------------------
When an ownCloud upgrade is available from ownCloud's `Open Build Service`_
repository, apply it just like any normal Linux upgrade. For example, on Debian
or Ubuntu Linux this is the standard system upgrade command::
$ sudo apt-get update && sudo apt-get upgrade
Or you can upgrade just ownCloud with this command::
$ sudo apt-get update && sudo apt-get install owncloud
On Fedora, CentOS, and Red Hat Linux use ``yum`` to see all available updates::
$ yum check-update
You can apply all available updates with this command::
$ sudo yum update
Or update only ownCloud::
$ sudo yum update owncloud
Your Linux package manager only downloads the current ownCloud packages. Then
your ownCloud server is automatically put into maintenance mode.
.. figure:: images/upgrade-1.png
:scale: 70%
:alt: ownCloud status screen informing users that it is in maintenance mode.
*Click to enlarge*
Next, take your server out of maintenance mode. You can do this by changing
``'maintenance' => true,`` to ``'maintenance' => false,`` in ``config.php``, or
use the :doc:`occ command <../configuration_server/occ_command>`, like this
example on Ubuntu::
$ sudo -u www-data php occ maintenance:mode --off
.. _upgrade_wizard_label:
Upgrade Wizard
--------------
The final step is to run the upgrade wizard to perform the final steps of
updating your apps and database. You will see a screen with a summary of apps
that are updated, and a **Start Update** button. If you have shell access it
is better to **not** click the Start Update button, but rather to use ``occ
upgrade``, like this example on CentOS::
$ sudo -u apache php occ upgrade
.. figure:: images/upgrade-2.png
:scale: 70%
:alt: ownCloud upgrade status screen
*Click to enlarge*
``occ upgrade`` is more reliable, especially on installations with large
datasets and large numbers of users because it avoids the risk of PHP timeouts.
When the upgrade is completed you will be returned to the login screen.
.. _migration_test_label:
Migration Test
^^^^^^^^^^^^^^
Before completing the upgrade, ownCloud first runs a simulation by copying all
database tables to a temporary directory and then performing the upgrade on
them, to ensure that the upgrade will complete correctly. This can delay large
installations by several hours, so you can omit this step with the
``--skip-migration-test`` option, like this example on CentOS::
$ sudo -u apache php occ upgrade --skip-migration-test
Setting Strong Permissions
^^^^^^^^^^^^^^^^^^^^^^^^^^
After upgrading, verify that your ownCloud directory permissions are set
according to :ref:`strong_perms_label`.
If the upgrade fails, then you must try a manual upgrade.
Manual Upgrade Procedure
------------------------
Always start by making a fresh backup.
If you are upgrading to a major release, for example from 8.1.3 to
8.2, you must review all third party applications (not core apps) for
compatibility with your new ownCloud version. Then disable all of them
before starting the upgrade.
Next put your server in maintenance mode. This prevents new logins, locks the
sessions of logged-in users, and displays a status screen so users know what is
happening. There are two ways to do this, and the preferred method is to use the
:doc:`occ command <../configuration_server/occ_command>`, which you must run as
your HTTP user. This example is for Ubuntu Linux::
$ sudo -u www-data php occ maintenance:mode --on
The other way is by entering your ``config.php`` file and changing
``'maintenance' => false,`` to ``'maintenance' => true,``.
1. Back up your existing ownCloud Server database, data directory, and
``config.php`` file. (See :doc:`backup`.)
2. Download and unpack the latest ownCloud Server release (Archive file) from
`owncloud.org/install/
<https://owncloud.org/install/>`_ into an empty directory outside
of your current installation. For example, if your current ownCloud is
installed in ``/var/www/owncloud/`` you could create a new directory called
``/var/www/owncloud2/``
3. Stop your Web server.
4. Rename or move your current ownCloud directory (named ``owncloud/`` if
installed using defaults) to another location.
5. Unpack your new tarball::
tar xjf owncloud-latest.tar.bz2
6. This creates a new ``owncloud/`` directory populated with your new server
files. Copy this directory and its contents to the original location of your
old server, for example ``/var/www/``, so that once again you have
``/var/www/owncloud`` .
7. Copy and paste the ``config.php`` file from your old version of
ownCloud to your new ownCloud version.
8. If you keep your ``data/`` directory in your ``owncloud/`` directory, copy
it from your old version of ownCloud to the ``owncloud/`` directory of
your new ownCloud version. If you keep it outside of ``owncloud/`` then
you don't have to do anything with it, because its location is configured in
your original ``config.php``, and none of the upgrade steps touch it.
.. note:: We recommend storing your ``data/`` directory in a location other
than your ``owncloud/`` directory.
9. If you are using third party applications, look into the ``owncloud/apps/``
directory to see if they are there. If not, copy them from your old ``apps/``
directory to your new one. Make sure the directory permissions of your third
party application directories are the same as for the other ones.
10. Restart your Web server.
11. Now launch the upgrade from the command line using ``occ`` to
avoid PHP timeouts, like this example on Ubuntu Linux::
$ sudo -u www-data php occ upgrade
.. note:: The ``occ`` command does not download ownCloud updates. You must first download
and install the updated code (steps 1-3), and then ``occ`` performs the final upgrade steps.
12. The upgrade operation takes a few minutes to a few hours, depending on the
size of your installation. When it is finished you will see a success
message, or an error message that will tell where it went wrong.
Assuming your upgrade succeeded, disable the maintenance mode::
$ sudo -u www-data php occ maintenance:mode --off
Login and take a look at the bottom of your Admin page to
verify the version number. Check your other settings to make sure they're
correct. Go to the Apps page and review the core apps to make sure the right
ones are enabled. Re-enable your third-party apps. Then apply strong
permissions to your ownCloud directories (:ref:`strong_perms_label`).
Reverse Upgrade
---------------
If you need to reverse your upgrade, see :doc:`restore`.
Troubleshooting
---------------
When upgrading ownCloud and you are running MySQL or MariaDB with binary logging
enabled, your upgrade may fail with these errors in your MySQL/MariaDB log::
An unhandled exception has been thrown:
exception 'PDOException' with message 'SQLSTATE[HY000]: General error: 1665
Cannot execute statement: impossible to write to binary log since
BINLOG_FORMAT = STATEMENT and at least one table uses a storage engine limited
to row-based logging. InnoDB is limited to row-logging when transaction
isolation level is READ COMMITTED or READ UNCOMMITTED.'
Please refer to :ref:`db-binlog-label` on how to correctly configure your environment.
Occasionally, *files do not show up after a upgrade*. A rescan of the files can help::
$ sudo -u www-data php console.php files:scan --all
See `the owncloud.org support page <http://owncloud.org/support>`_ for further
resources for both home and enterprise users.
Sometimes, ownCloud can get *stuck in a upgrade*. This is usually due to the
process taking too long and encountering a PHP time-out. Stop the upgrade
process this way::
$ sudo -u www-data php occ maintenance:mode --off
Then start the manual process::
$ sudo -u www-data php occ upgrade
If this does not work properly, try the repair function::
$ sudo -u www-data php occ maintenance:repair
Then review third-party apps, if you have any, for compatibility with the new
ownCloud release. Any apps that are not developed by ownCloud show a 3rd party
designation. **Install unsupported apps at your own risk**. Then, before the
upgrade, all 3rd party apps must be disabled. After the upgrade is complete you
may re-enable them.
.. _Open Build Service:
https://download.owncloud.org/download/repositories/8.2/owncloud/
.. _owncloud.org/install/:
https://owncloud.org/install/