Upgrading Your ownCloud Server¶
Starting with version 8.0.9, ownCloud will be automatically put into maintenance mode after downloading upgraded packages. You must take it out of maintenance mode and then run the upgrade wizard to complete the upgrade.
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. Skipping major releases is not supported.
There are multiple ways to keep your ownCloud server upgraded: with the Updater App (Community 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 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 Installing & Upgrading ownCloud Enterprise Edition 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.
Warning
Downgrading is not supported and risks corrupting your data! If you want to revert to an older ownCloud version, make a new, fresh installation and then restore your data from backup. Before doing this, 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¶
The best method for keeping ownCloud on Linux servers current is by configuring your system to use the openSUSE Build Service (see Preferred Linux Installation Method); just follow the instructions on oBS for setting up your package manager. Then stay current by using your Linux package manager to upgrade fresh packages, and then run a few more steps to complete the upgrade. These are the basic steps to upgrading ownCloud:
- Disable all third-party apps.
- Make a fresh backup.
- Install new packages from the openSUSE Build Service.
- Take your ownCloud server out of maintenance mode (ownCloud 8.1.4+).
- Run the upgrade wizard (optionally disabling the migration test).
- Log in and apply strong permissions to your ownCloud directories.
- Re-enable third-party apps.
Note
If you are using the Encryption app and upgrading from older versions of ownCloud to ownCloud 8.0, you must manually migrate your encryption keys with the occ command after the upgrade is complete, like this example for CentOS: sudo -u apache php occ encryption:migrate-keys You must run occ as your HTTP user. See Using the occ Command to learn more about occ
Prerequisites¶
You should always maintain 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.
Encryption migration from oC 7.0 to 8.0¶
The encryption backend was changed between ownCloud 7.0 and 8.0. If you’re upgrading from this older version please refer to Encryption migration to ownCloud 8.0 for the needed migration steps.
Upgrading With Your Linux Package Manager¶
When an ownCloud upgrade is available from the openSUSE 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.
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 occ command, like this
example on Ubuntu:
$ sudo -u www-data php occ maintenance:mode --off
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
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¶
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 Setting Strong Directory Permissions.
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 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,
.
- Back up your existing ownCloud Server database, data directory, and
config.php
file. (See Backing up ownCloud.) - 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
To unpack your new tarball:: tar xjf owncloud-latest.tar.bz2
- Stop your Web server.
- Rename or move your current ownCloud directory (named
owncloud/
if installed using defaults) to another location. - 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
. - Copy and paste the
config.php
file from your old version of ownCloud to your new ownCloud version. - If you keep your
data/
directory in yourowncloud/
directory, copy it from your old version of ownCloud to theowncloud/
directory of your new ownCloud version. If you keep it outside ofowncloud/
then you don’t have to do anything with it, because its location is configured in your originalconfig.php
, and none of the upgrade steps touch it.
Note
We recommend storing your data/
directory in a location other
than your owncloud/
directory.
Restart your Web server.
- Now you should be able to open a Web browser to your ownCloud server and
log in as usual. You have a couple more steps to go: You should see a Start Update screen, just like in the Upgrading With Your Linux Package Manager section, above. Review the prerequisites, and if you have followed all the steps click the Start Update button.
If you are running a large installation with a lot of files and users, you should 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 thenocc
performs the final upgrade steps.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, 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 (Setting Strong Directory Permissions).
Upgrading Across Skipped Releases¶
It is best to update your ownCloud installation with every new point release, and to never skip any major releases. If you have skipped any major releases you can bring your ownCloud current with these steps:
- Add the repository of your current version
- Upgrade your current version to the latest point release
- Add the repo of the next major release
- Upgrade your current version to the next major release
- Run upgrade routine
- Repeat from step 3 until you reach the last available major release
You’ll find previous ownCloud releases in the ownCloud Server Changelog.
If upgrading via your package manager fails, then you must perform a Manual Upgrade Procedure.
Previous ownCloud Releases¶
You’ll find previous ownCloud releases in the ownCloud Server Changelog.
Reverse Upgrade¶
If you need to reverse your upgrade, see Restoring ownCloud.
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 MySQL / MariaDB with Binary Logging Enabled 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
Encryption migration from oC 7.0 to 8.0 and 8.0 to 8.1¶
The encryption backend was changed twice between ownCloud 7.0 and 8.0 as well as between 8.0 and 8.1. If you’re upgrading from these older versions please refer to Encryption migration to ownCloud 8.0 for the needed migration steps.
Debian Migration to Official ownCloud Packages¶
As of March 2016 Debian will not include ownCloud packages. Debian users can migrate to the official ownCloud packages by following this guide, Upgrading ownCloud on Debian Stable to official packages.