Manual ownCloud Upgrade

Preparation

This section describes how to manually upgrade your ownCloud installation.

Enable Maintenance Mode

Put your server in maintenance mode and disable Cron jobs. Doing so prevents new logins, locks the sessions of logged-in users, and displays a status screen so that users know what is happening.

There are two ways to enable maintenance mode.

  1. The preferred method is to use the occ command — which you must run as your webserver user.

    # Enable maintenance mode using the occ command.
    sudo -u www-data php occ maintenance:mode --on
  2. The other way is by changing the value in your config.php file and replacing 'maintenance' ⇒ false, to 'maintenance' ⇒ true,.

In a clustered environment please check that all nodes are in maintenance mode.

Stop the Webserver

With those steps completed, stop your webserver.

# Stop the web server
sudo service apache2 stop

Backup Your Existing Installation

First, backup the following items:

  1. The complete ownCloud directory

  2. The ownCloud server database

# This example assumes Ubuntu Linux and MariaDB
# Rename owncloud directory
mv /var/www/owncloud /var/www/owncloud-old-version-number
# Backup the Database
mysqldump -u<username> -p<password> <databasename> > <ownCloud-Version-Dump.sql>

In clustered environment please check that all nodes are in maintenance mode.

Review Third-Party Apps

Review any installed third-party apps for compatibility with the new ownCloud release. Ensure that they are all disabled before beginning the upgrade. Third party apps are all apps that are not distributed by ownCloud

  1. Disable via Command Line

    # This command lists all apps by <app-id> and app version
    sudo -u www-data php occ app:list
    
    # This command disables the app with the given <app-id>
    sudo -u www-data php occ app:disable <app-id>
  2. Disable via Browser
    Goto Settings  Admin  Apps and disable all third-party apps

Download the Latest Installation

Download the latest wnCloud server release where your current installation was. In this example /var/www/

cd /var/www/
wget https://download.owncloud.org/community/owncloud-10.2.1.tar.bz2
Enterprise users must download their new ownCloud archives from their accounts on https://customer.owncloud.com/owncloud/.

To download the tarball from https://customer.owncloud.com you will need a command like this:

wget https://username:password@customer.owncloud.com/link-to-tarball

Upgrade

For this description we assume that your existing ownCloud installation is located in the default location: /var/www/owncloud. The path might differ, depending on your installation.

Extract the New Source

Extract the new server release in the location of your original ownCloud installation.

tar -xvf owncloud-10.2.1.tar.bz2

With the new source files now in place of the old ones, next copy the config.php file from your old ownCloud directory to your new ownCloud directory:

sudo cp /var/www/owncloud-old-version-number/config/config.php /var/www/owncloud/config/config.php

If you keep your data/ directory inside your owncloud/ directory, move it from your old version of ownCloud to your new version:

mv /var/www/owncloud-old-version-number/data /var/www/owncloud/data

If you keep your data outside of your owncloud directory, 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.

Market and Marketplace App Upgrades

Before getting too far into the upgrade process, please be aware of how the Market app and its configuration options affect the upgrade process.

The Market app — and other apps from the Marketplace — will not be updated when you upgrade ownCloud, if upgrade.automatic-app-update is set to true in config.php.

In addition, if there are installed apps (whether compatible or incompatible with the next version, or missing source code) and the Market app is enabled but there is no available internet connection, these apps will need to be manually updated once the upgrade is finished.

Copy Old Apps

If you are using third party or enterprise applications, look in your new /var/www/owncloud/apps/ directory to see if they are present. If not, copy them from your old apps/ directory to your new one.

Setting the Ownership for Upgrading

To finalize the preparation of the upgrade, you need to set the correct ownership of the new ownCloud files and folders. Here is a neat little bash-script to do this on the fly. You will need to change the paths and webserver users according to your installation and/or Linux Distribution.

Take your favourite editor and create the oc_permit.sh and copy the contents from beneath.

#!/bin/bash

set -o pipefail
set -o errtrace
set -o nounset

# Please update the paths in the variables below to suit your installation.
htuser='settermjd'
htgroup='staff'
logfile='output.log'
ocpath=''
ocstorage=''
rootuser='root'

if [[ ! -e "$ocpath" ]] || [[ -z "$ocpath" ]] || [[ ! -e "$ocstorage" ]] || [[ -z "$ocstorage" ]]; then
    printf "Either one or both of the ownCloud root and data directories are missing.\n"
    printf "Please check that the values set for ocpath and ocstorage are correct before running the script.\n"
    printf "Exiting.\n"
    exit -1;
fi

if [[ ! -e "$ocstorage/data" ]]; then
    printf "Creating missing ownCloud data directory\n"
    mkdir -p $ocstorage/data
fi

printf "Updating file and directory permissions of the ownCloud directory\n"
find "${ocpath}/" -type f -print0 | xargs -0 chmod 0640 >> $logfile 2>&1
find "${ocpath}/" -type d -print0 | xargs -0 chmod 0750 >> $logfile 2>&1

printf "Updating owner of the ownCloud apps and config directories.\n"
chown -R "${rootuser}:${htgroup}" "${ocpath}/" >> $logfile 2>&1
if [ $? -ne 0 ]; then
    printf "  Unable to recursively set owner and group on [%s].\n" "${ocpath}/"
fi

chown -R "${htuser}:${htgroup}" "${ocpath}/apps/" >> $logfile 2>&1
if [ $? -ne 0 ]; then
    printf "  Unable to recursively set owner and group on [%s].\n" "${ocpath}/apps/"
fi

chown -R "${htuser}:${htgroup}" "${ocpath}/config/" >> $logfile 2>&1
if [ $? -ne 0 ]; then
    printf "  Unable to recursively set owner and group on [%s].\n" "${ocpath}/config/"
fi

printf "Updating ownCloud storage directory and file permissions.\n"
find "${ocstorage}/" -type f -print0 | xargs -0 chmod 0640 >> $logfile 2>&1
find "${ocstorage}/" -type d -print0 | xargs -0 chmod 0750 >> $logfile 2>&1

chmod +x "${ocpath}/occ"

printf "Updating .htaccess owner and permissions.\n"
if [ -f "${ocpath}/.htaccess" ]; then
  chmod 0644 "${ocpath}/.htaccess" >> $logfile 2>&1
  if [ $? -ne 0 ]; then
    printf "  Unable to set permissions on [%s].\n" "${ocpath}/.htaccess"
  fi

  chown "${rootuser}:${htgroup}" "${ocpath}/.htaccess" >> $logfile 2>&1
  if [ $? -ne 0 ]; then
    printf "  Unable to set owner and group on [%s].\n" "${ocpath}/.htaccess"
  fi
fi

if [ -f "${ocstorage}/data/.htaccess" ]; then
  chmod -f 0644 "${ocstorage}/data/.htaccess" >> $logfile 2>&1
  if [ $? -ne 0 ]; then
    printf "  Unable to set permissions on [%s].\n" "${ocstorage}/data/.htaccess"
  fi

  chown "${rootuser}:${htgroup}" "${ocstorage}/data/.htaccess" >> $logfile 2>&1
  if [ $? -ne 0 ]; then
    printf "  Unable to set owner and group on [%s].\n" "${ocstorage}/data/.htaccess"
  fi
fi

echo "Finished."
echo "Exiting."

Save and close the file and make it executable by running chmod +x oc_permit.sh. Then, run sh oc_permit.sh. You can find a more sophisticated script right here: strong permissions.

You can also use this command, if you don’t want to use the script:

sudo chown -R www-data:www-data /var/www/owncloud

Start the Upgrade

With the apps disabled and ownCloud in maintenance mode, start the upgrade process from the command line:

# Here is an example on Ubuntu Linux.
# Execute this within the ownCloud root folder.
sudo -u www-data php occ upgrade

The upgrade operation can take anywhere from a few minutes to a few hours, depending on the size of your installation. When it is finished you will see either a success message, or an error message which indicates why the process did not complete successfully.

Disable Maintenance Mode

Assuming your upgrade succeeded, next disable maintenance mode.

# Disable maintenance mode using the occ command.
sudo -u www-data php occ maintenance:mode --off

Restart the Webserver

With all that done, restart your web server:

sudo service apache2 start

Finalize the Installation

With maintenance mode disabled, login and:

  • Check that the version number reflects the new installation.
    It can be reviewed at the bottom of Settings  Admin  General.

  • Check that your other settings are correct.

  • Go to the Settings  Admin  Apps page and review the core apps to make sure the right ones are enabled.

  • After the upgrade is complete, re-enable any third-party apps that are compatible with the new release.

    1. Enable via Command Line

      # This command enables the app with the given <app-id>
      sudo -u www-data php occ app:enable <app-id>
    2. Enable via Browser

Go to Settings  Admin  Apps  "Show disabled apps" and enable all compatible third-party apps

+ WARNING: Install or enable unsupported apps at your own risk.

Rollback

If you need to rollback your upgrade, see the Restoring ownCloud documentation.

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

In the unlikely case that files do not show up in the web-ui after the upgrade, use the files:scan command to make them visible again. Here is an example of how to do so:

sudo -u www-data php occ 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