Migrating to a Different Server

Introduction

If the need arises, ownCloud can be migrated to a different server. A typical use case would be a hardware change or a migration from the Enterprise appliance to a physical server. All migrations have to be performed with ownCloud in maintenance mode. Online migration is supported by ownCloud only when implementing industry-standard clustering and high-availability solutions before ownCloud is installed for the first time.

To start, let’s work through a potential use case. A configured ownCloud instance runs reliably on one machine, but for some reason the instance needs to be moved to a new machine. Depending on the size of the ownCloud instance the migration might take several hours.

For the purpose of this use case, it is assumed that:

  1. The end users reach the ownCloud instance via a virtual hostname (such as a DNS CNAME record) which can be pointed at the new location.

  2. The authentication method (e.g., LDAP) remains the same after the migration.

During the migration, do not make any changes to the original system, except for putting it into maintenance mode. This ensures, should anything unforeseen happen, that you can go back to your existing installation and resume availability of your installation while debugging the problem.

How to Migrate

Firstly, set up the new machine with your desired Linux distribution. At this point you can either install ownCloud manually via the compressed archive, or with your Linux Package Manager.

Then, on the original machine turn on maintenance mode and then stop ownCloud. After waiting 6 - 7 minutes for all sync clients to register that the server is in maintenance mode, stop the web server that is serving ownCloud.

After that, create a database dump from the database, copy it to the new machine and import it into the new database. Then, copy only your data, configuration, and database files from your original ownCloud instance to the new machine.

You must keep the data/ directory’s original file path during the migration. However, you can change it before you begin the migration, or after the migration’s completed.

The data files should keep their original timestamp otherwise the clients will re-download all the files after the migration. This step might take several hours, depending on your installation. This can be done on a number of sync clients, such as by using rsync with -t option

With ownCloud still in maintenance mode and before changing the DNS CNAME record, start up the database and web server on the new machine. Then point your web browser to the migrated ownCloud instance and confirm that:

  1. You see the maintenance mode notice

  2. That a log file entry is written by both the web server and ownCloud

  3. That no error messages occur.

If all of these things occur, then take ownCloud out of maintenance mode and repeat. After doing this, log in as an admin and confirm that ownCloud functions as normal.

At this point, change the DNS CNAME entry to point your users to the new location. And with the CNAME entry updated, you now need to update the trusted domains.

Managing Trusted Domains

All URLs used to access your ownCloud server must be white-listed in your config.php file, under the trusted_domains setting. Users are allowed to log into ownCloud only when they point their browsers to a URL that is listed in the trusted_domains setting.

This setting is important when changing or moving to a new domain name. You may use IP addresses and domain names.

A typical configuration looks like this:

'trusted_domains' => [
   0 => 'localhost',
   1 => 'server1.example.com',
   2 => '192.168.1.50',
],

The loopback address, 127.0.0.1, is automatically white-listed, so as long as you have access to the physical server you can always log in. In the event that a load-balancer is in place, there will be no issues as long as it sends the correct X-Forwarded-Host header.

In case of a docker based setup, the trusted_domains setting is controlled by the environment variables OWNCLOUD_TRUSTED_DOMAINS or OWNCLOUD_DOMAIN. The latter only takes effect, if OWNCLOUD_TRUSTED_DOMAINS is undefined and can provide one IP-address or hostname. OWNCLOUD_TRUSTED_DOMAINS can specify multiple values as a comma-separated list.

Here is an example of how this can be used from within a docker-compose.yml file to allow access to ownCloud under two different names, and one IP-address, in addition to localhost and 127.0.0.1:

services:
  owncloud:
    image: "owncloud/server:10.15"
    environment:
      OWNCLOUD_TRUSTED_DOMAINS: "myowncloud.mydomain.com, myowncloud, 12.23.34.45"
...

Example Migration

The following is an example migration with assumptions to make this migration work:

  • Ubuntu 20.04+

  • SSH with PermitRootLogin set to yes

  • Database used is MySQL / MariaDB

Preparation

If not already available on the new server, make sure SSH is installed:

sudo apt install ssh -y

Next, edit ssh-config and enable root ssh login.

nano /etc/ssh/sshd_config
PermitRootLogin yes

And then restart SSH.

sudo service ssh restart

Lastly, install ownCloud on the new server.

Migration

Enable Maintenance Mode

The first step is to enable maintenance mode. To do that, use the following commands:

cd /var/www/owncloud/
sudo -u www-data ./occ maintenance:mode --on

After that’s done, then wait a few minutes and stop your web server, in this case Apache:

sudo service apache2 stop

Transfer the Database

Now, you have to transfer the database from the old server to the new one. To do that, first backup the database.

cd /var/www/owncloud/
mysqldump --single-transaction -h localhost \
    -u admin -ppassword owncloud > owncloud-dbbackup.bak

Then, export the database to the new server.

rsync -v owncloud-dbbackup.bak root@new_server_address:/var/www/owncloud

With that completed, import the database on new server.

mysql -h localhost -u admin -ppassword owncloud < owncloud-dbbackup.bak
You can find the values for the mysqldump command in your config.php, in your owncloud root directory. [server]= dbhost, [username]= dbuser, [password]= dbpassword, and [db_name]= dbname.
For InnoDB tables only

The –single-transaction flag will start a transaction before running. Rather than lock the entire database, this will let mysqldump read the database in the current state at the time of the transaction, making for a consistent data dump.
For Mixed MyISAM / InnoDB tables

Either dumping your MyISAM tables separately from InnoDB tables or use --lock-tables instead of --single-transaction to guarantee the database is in a consistent state when using mysqldump.

Transfer Data and Configure the New Server

The following ownCloud directories will be synced to the target instance: apps, config and data.

rsync -avt apps config data root@new_server_address:/var/www/owncloud
If you have an additional apps directory like apps-external, this directory needs to be added to the sync list above.
If you want to move your data directory to another location on the target server, it is advised to do this as a second step. Please see the data directory migration document for more details.

Finish the Migration

Now it’s time to finish the migration. To do that, on the new server, first verify that ownCloud is in maintenance mode.

sudo -u www-data ./occ maintenance:mode

Next, start up the database and web server on the new machine.

sudo service mysql start
sudo service apache2 start

With that done, point your web browser to the migrated ownCloud instance, and confirm that you see the maintenance mode notice, and that no error messages occur. If both of these occur, take ownCloud out of maintenance mode.

sudo -u www-data ./occ maintenance:mode --off

And finally, log in as admin and confirm normal function of ownCloud. If you have a domain name, and you want an SSL certificate, we recommend certbot.

Reverse the Changes to ssh-config

Now you need to reverse the change to ssh-config. Specifically, set PermitRootLogin to no and restart ssh. To do that, run the following command:

This is a security measure and improves SSH security. 
sudo service ssh restart

Update DNS and Trusted Domains

Finally, update the DNS’ CNAME entry to point to your new server. If you have not only migrated physically from server to server but have also changed your ownCloud server’s domain name, you also need to update the domain in the Trusted Domain setting in config.php, on the target server.