diff --git a/admin_manual/maintenance/images/2-updates.png b/admin_manual/maintenance/images/2-updates.png new file mode 100644 index 000000000..35a99017c Binary files /dev/null and b/admin_manual/maintenance/images/2-updates.png differ diff --git a/admin_manual/maintenance/images/upgrade-2.png b/admin_manual/maintenance/images/upgrade-2.png index 17cab4d87..eab59954b 100644 Binary files a/admin_manual/maintenance/images/upgrade-2.png and b/admin_manual/maintenance/images/upgrade-2.png differ diff --git a/admin_manual/maintenance/images/upgrade-3.png b/admin_manual/maintenance/images/upgrade-3.png new file mode 100644 index 000000000..141169f25 Binary files /dev/null and b/admin_manual/maintenance/images/upgrade-3.png differ diff --git a/admin_manual/maintenance/images/upgrade-notifier.png b/admin_manual/maintenance/images/upgrade-notifier.png new file mode 100644 index 000000000..8f307666d Binary files /dev/null and b/admin_manual/maintenance/images/upgrade-notifier.png differ diff --git a/admin_manual/maintenance/index.rst b/admin_manual/maintenance/index.rst index 4f6fb4800..7606a1e25 100644 --- a/admin_manual/maintenance/index.rst +++ b/admin_manual/maintenance/index.rst @@ -8,6 +8,8 @@ Maintenance enable_maintenance backup upgrade + package_upgrade + manual_upgrade update restore migrating diff --git a/admin_manual/maintenance/manual_upgrade.rst b/admin_manual/maintenance/manual_upgrade.rst new file mode 100644 index 000000000..83d85fc24 --- /dev/null +++ b/admin_manual/maintenance/manual_upgrade.rst @@ -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 ``_ + +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 `_ 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/ + \ No newline at end of file diff --git a/admin_manual/maintenance/package_upgrade.rst b/admin_manual/maintenance/package_upgrade.rst new file mode 100644 index 000000000..b86b7ea66 --- /dev/null +++ b/admin_manual/maintenance/package_upgrade.rst @@ -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 `. +* Install new packages from the ownCloud `Open Build Service`_. +* Take your ownCloud server out of :doc:`maintenance mode + `. +* Run the :ref:`upgrade wizard ` or + ``occ upgrade`` (optionally disabling the :ref:`migration test + `). +* :ref:`apply strong permissions ` 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/ \ No newline at end of file diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst index f2a7136ed..899ebc133 100644 --- a/admin_manual/maintenance/upgrade.rst +++ b/admin_manual/maintenance/upgrade.rst @@ -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 ` with our `Open + Build Service`_ repository. This is the recommended method. +* With the :doc:`Updater App ` (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 ` 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 ` (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 `. -* Install new packages from the ownCloud `Open Build Service`_. -* Take your ownCloud server out of :doc:`maintenance mode - `. -* Run the :ref:`upgrade wizard ` (optionally disabling - the :ref:`migration test `). -* Log in and :ref:`apply strong permissions ` 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 ` 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/ - `_ 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 `_ 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/ \ No newline at end of file