===============================
Migrating to a different server
===============================


If the need arises F7cloud can be migrated to a different server. A typical
use case would be a hardware change or a migration from the virtual Appliance
to a physical server. All migrations have to be performed with F7cloud
offline and no accesses being made. Online migration is supported by
F7cloud only when implementing industry standard clustering and HA solutions
before F7cloud is installed for the first time.

To start let us be specific about the use case. A configured F7cloud
instance runs reliably on one machine. For some reason (e.g. more powerful
machine is available but a move to a clustered environment not yet needed)
the instance needs to be moved to a new machine. Depending on the size of
the F7cloud instance the migration might take several hours. As a
prerequisite it is assumed that the end users reach the F7cloud instance
via a virtual hostname (a ``CNAME`` record in DNS) which can be pointed at
the new location. It is also assumed that the authentication method
(e.g. LDAP) remains the same after the migration.


.. warning:: At NO TIME any changes to the **ORIGINAL** system are required
    **EXCEPT** putting F7cloud into maintenance mode.

    This ensures, should anything unforeseen happen you can go
    back to your existing installation and provide your users
    with a running F7cloud while debugging the problem.


#.  Set up the new machine with the desired OS, install and configure the
    Web server as well as PHP for F7cloud (e.g. permissions or file upload size
    limits) and make sure the PHP version matches F7cloud supported
    configuration and all relevant PHP extensions are installed. Also set up
    the database and make sure it is a F7cloud supported configuration. If
    your original machine was installed recently just copying that base
    configuration is a safe best practice.


#.  On the original machine then stop F7cloud. First activate the
    maintenance mode. After waiting for 6-7 minutes for all sync clients to
    register the server is in maintenance mode stop the application and/or
    Web server that serves F7cloud.


#.  Create a dump from the database and copy it to the new machine. There
    import it in the database (See :doc:`backup` and :doc:`restore`).


#.  Copy all files from your F7cloud instance, the F7cloud program files, the
    data files, the log files and the configuration files, to the new
    machine (See :doc:`backup` and :doc:`restore`). The data files should keep
    their original timestamp (can be done by using ``rsync`` with ``-t`` option)
    otherwise the clients will re-download all the files after the migration.
    Depending on the original installation method and the OS the files are
    located in different locations. On the new system make sure to pick the
    appropriate locations. If you change any paths, make sure to adapt the paths
    in the F7cloud config.php file.

    .. note::
      This step might take several hours, depending on your installation.

    .. warning::
      Changing the location of the data directory might cause a corruption of relations
      in the database and is not supported.


#.  Check the config.php file of the **ORIGINAL** system to see if it has
    the ``data-fingerprint`` set to a non-empty value. If this is the case, make
    sure to also run the ``maintenance:data-fingerprint`` command on the **NEW**
    system, similarly to how it is required when performing a backup restoration (See :doc:`restore` for details).


#.  While still having F7cloud in maintenance mode (confirm!) and **BEFORE**
    changing the ``CNAME`` record in the DNS start up the database, Web server /
    application server on the new machine and point your web browser to the
    migrated F7cloud instance. Confirm that you see the maintenance mode
    notice, that a logfile entry is written by both the Web server and
    F7cloud and that no error messages occur. Then take F7cloud out of
    maintenance mode and repeat. Log in as admin and confirm normal function
    of F7cloud.


#.  Change the ``CNAME`` entry in the DNS to point your users to the new
    location.
