.. _move-docker:

==============================
Move Fleio Docker installation
==============================

Use this guide to copy or move a Fleio Docker installation (including database, settings and customizations) to another
server.

This guide only applies for Docker to Docker Fleio deployment method. If you are migrating from a legacy DEB/RPM Fleio
install follow :ref:`debrpm-to-docker`.

The guide applies when **copying** an installation, that is you keep the old installation running and also run Fleio on
the new installation, and when **moving** the old installation, in other words you are stopping the old server and after
copying data, you will only run Fleio on the new server. There are notes in the guide regarding copying and moving.

Here are some typical use cases for this guide:

* You have a lab evaluation of Fleio and you want to keep all the settings and move to a production server.
* You have a production server, and you want to duplicate the database and all the settings to a staging installation,
  where you can test Fleio upgrades or customizations, before applying them to production.
* You want to move your production Fleio server to another production server.

.. contents:: :local:

1. Install Fleio from scratch on the new server
===============================================

.. note::

    Make sure you install the exact same version on the new server as the version on the old server.

    You need an extra license key to install Fleio on the new server. For staging/development installations, contact
    support to obtain a free license key for each Fleio license you have purchased.

    Decide on the URL to use for your new Fleio installation and use it for the ``FLEIO_FRONTEND_URL`` variable below.
    Note that the URL is linked to the license during installation.

    After the initial Fleio installation, if you later change the installation URL or the secret key, you will need a
    Fleio license reset. Contact Fleio support to reset your license.

    For moving a (production) installation, this guide assumes that you have a strategy for pointing your users to the
    new Fleio installation. As last production move step, you can move IP address to new server, update DNS
    settings etc. This guide does not cover this part.

    ``http://192.168.99.2`` and ``https://mydomain.com`` are used below as examples. Replace with your URLs.

1.1. Installing Fleio version 2022.11 or newer
----------------------------------------------

Install the **exact same Fleio version** as the one on the old server.

If you are moving Fleio version 2022.11 or newer, you can also specify in the ``install`` command the
``FLEIO_DJANGO_SECRET_KEY`` from the old server. This will spare you to ask support for a license reset.

To get the ``FLEIO_DJANGO_SECRET_KEY`` run this **on the old server** (from which you are migrating):

.. code-block:: bash

    fleio bash cat fleio/fleiosettings/settings.py|grep -m 1 SECRET_KEY
    # you'll get something like:
    # SECRET_KEY = '<< the secret key >>'
    # Copy << the secret key >>

Run the ``install`` command **on the new server** (to which you are migrating).

.. code-block:: bash

    curl -s -o install https://fleio.com/install && sudo \
    FLEIO_LICENSE_ID="<< license id >>" \
    FLEIO_LICENSE_KEY="<< license key >>" \
    FLEIO_FRONTEND_URL="http://192.168.99.2" \
    FLEIO_DJANGO_SECRET_KEY="<< the secret key >>" \
    bash install << replace with Fleio version to install >>

The ``install`` script will ask you for details like time zone. You may fill any values, they are overwritten anyway
when you later copy the settings from the old Fleio installation.

1.2. Installing Fleio version older than 2022.11
------------------------------------------------

Install the **exact same Fleio version** as the one on the old server.

Run the ``install`` command **on the new server** (to which you are migrating). Since a secret key is randomly generated
during installation, and you will later need to set this value to the one from the old server, a license reset will be
required. After completing the migration steps, contact support to reset your license.

.. code-block:: bash

    curl -s -o install https://fleio.com/install && sudo \
    FLEIO_LICENSE_ID="<< license id >>" \
    FLEIO_LICENSE_KEY="<< license key >>" \
    FLEIO_FRONTEND_URL="http://192.168.99.2" \
    bash install << replace with Fleio version to install >>

The ``install`` script will ask you for details like time zone. You may fill any values, they are overwritten anyway
when you later copy the settings from the old Fleio installation.

2. Copy settings from the old server
====================================

.. note::

    The following commands work for Fleio version 2022.11 and newer. If you have an older version, replace the ``-`` 
    (minus) in the container names with ``_`` (underscore). E.g., ``fleio-backend-1`` is ``fleio_backend_1`` in Fleio
    versions older than 2022.11.

**On the old server**, copy the settings files from Docker containers to current host path:

.. code-block:: bash

    docker cp fleio-frontend-1:/var/webapps/fleio/frontend/enduser/assets/config/enduser.config.json enduser.config.json
    docker cp fleio-frontend-1:/var/webapps/fleio/frontend/staff/assets/config/staff.config.json staff.config.json
    docker cp fleio-backend-1:/var/webapps/fleio/project/fleio/fleiosettings/settings.py settings.py

Use ``scp`` command a or a similar tool to copy the three files above (``settings.py``, ``enduser.config.json`` and
``staff.config.json``) **from the old server to the new server**.

While logged in to **the new server**, copy the settings files from host to Docker containers (make sure the three files
are in the current path):

.. code-block:: bash

    docker cp enduser.config.json fleio-frontend-1:/var/webapps/fleio/frontend/enduser/assets/config/enduser.config.json
    docker cp staff.config.json fleio-frontend-1:/var/webapps/fleio/frontend/staff/assets/config/staff.config.json
    docker cp settings.py fleio-backend-1:/var/webapps/fleio/project/fleio/fleiosettings/settings.py

Run ``fleio edit enduser.config.json`` and update the ``backendApiUrl`` to the URL you are using on the new server. For
example, for value ``"backendApiUrl": "//mydomain.com/backend/api/",``, only replace ``mydomain.com``. Do not add
``http`` or ``https``.

Run ``fleio edit staff.config.json`` and update the ``"backendApiUrl": "//mydomain.com/backend/staffapi/"`` just like
above. 

While still logged in to the **new server**, copy the database password shown by command:

.. code-block:: bash

    cat /home/fleio/compose/secrets/.db_password

Then run ``fleio edit settings.py`` and update the ``'PASSWORD': '<< copy here>>',`` value from the ``DATABASES = {``
section.

**If you are changing the old URL to a new URL**, while still editing ``settings.py``, update the following values based
on the URL you are using on the new server:

* ``ALLOWED_HOSTS = ['mydomain.com']`` - do not add ``http/s`` or a trailing slash
* ``FRONTEND_URL = 'https://mydomain.com'``

3. Copy the database
====================

Disable periodic tasks on the **old server**. You can find this setting in the staff panel, *Settings* > *General* >
*Advanced settings* tab. After checking *Disable periodic tasks*, wait a couple of minutes for this to take effect. 
**Keep in mind that you will later need to re-enable periodic tasks**, there's a note about this in a step below.

You can confirm that periodic tasks are no longer running by using this command:

.. code-block:: bash

    fleio list periodic

.. warning::

    If you are moving a Fleio installation (production or not), you need to stop Fleio on the old server. This way you
    ensure that there are no changes performed on the old database and you will have the latest version on the new
    server.

    When moving a production installation, it is highly recommended that you first perform a test move, and keep the old
    installation running. Once you confirm that the test move is successful, perform the steps again (starting with this
    one) on the final move (with old installation stopped).

Optionally, stop Fleio on the old server if you are performing **a move, not a copy**:

.. code-block:: bash

    cd /home/fleio/compose/
    # on Fleio version 2022.11 or newer, run:
    docker compose down
    docker compose up -d db
    # on Fleio version 2022.10 or older, run:
    # docker-compose down
    # docker-compose up -d db

Backup the database **from the old server**:

.. code-block:: bash

    fleio mysqldump | gzip > fleio_backup.gz

Copy the ``fleio_backup.gz`` backup file, by using ``scp``, **from the old server to the new server** in
``/home/fleio/compose`` path.

Restore from backup **on the new server** (uncomment the corresponding lines based on your Fleio version:

.. code-block:: bash

    cd /home/fleio/compose
    db_pass=$(cat secrets/.db_password)
    # on Fleio version 2022.11 or newer, run:
    # docker compose down
    # docker compose up -d db
    # on Fleio version 2022.10 or older, run:
    # docker-compose down
    # docker-compose up -d db
    # on Fleio version 2022.10 or older, run:
    # gunzip -c fleio_backup.gz | docker-compose exec -T db mysql fleio -u fleio -p"$db_pass"
    # on Fleio version 2022.11 or newer, run:
    # gunzip -c fleio_backup.gz | docker compose exec -T db mysql fleio -u fleio -p"$db_pass"

4. Set a new OpenStack notifications pool (when copying)
========================================================

.. warning::

    After copying the database, your new installation contains the same OpenStack notifications pool name.

    This means if the old and the new installations are running, some of the OpenStack notifications would be consumed 
    by the old installation and some by the new. This has serious consequences: OpenStack objects status may not get
    updated and usage/cost tracking will not work correctly.

    If you are moving Fleio (not copying) and the old installation will remain stopped, this step is not necessary.

.. code-block:: bash

    cd /home/fleio/compose/
    db_pass=$(cat secrets/.db_password)
    sql="UPDATE conf_option SET value='new-pool' WHERE section='OPENSTACK_PLUGIN' AND field='notifications_pool';"
    # on Fleio version 2022.10 or older, run:
    # echo "$sql" | docker-compose exec -T db mysql fleio -u fleio -p"$db_pass"
    # on Fleio version 2022.11 or newer, run:
    # echo "$sql" | docker compose exec -T db mysql fleio -u fleio -p"$db_pass"

5. Copy Fleio customizations (optional)
=======================================

If you have made any customizations to your (old) Fleio installation you need to copy the corresponding files from
``/home/fleio/compose`` to the same path on the new server:

* ``docker-compose.override.yml``
* files and directories you have created to customize the Docker images
* ``.env``, if you customized stuff like number of uWSGI processes. Note that you need to merge the values for domain
  and URL if they are different on the new server.

.. note::

    Do not copy the full ``/home/fleio/compose`` directory, as this will overwrite settings you do not want, like
    database password (``/home/fleio/compose/secrets/.db_password``) or Fleio installation URL (in ``.env``)

6. Recreate Fleio containers
============================

**On the new server**, run:

.. code-block:: bash

    fleio recreate

7. Ask for license reset
========================

If you have changed the new installation secret key or URL after the initial installation, your new installation will
not work anymore without a license reset. Contact the Fleio support to reset your license.

8. Enable periodic tasks
========================

If the new installation is a production installation, you need to enable periodic tasks. If it's a staging/development
installation, which just shadows the main/production installation, **do not enable periodic tasks**.

Enabling periodic tasks will start clients processing: calculate up-to-date usage, send email notification,
automatically suspend and terminate services, based on settings.

Enable periodic tasks **on the new server**. Uncheck *Disable periodic tasks* from the staff panel, *Settings* >
*General* > *Advanced settings* tab.

If you want to keep the old Fleio installation running while the new installation is also running, make sure you changed
the pool name on the new server (step 4 above) and uncheck *Disable periodic tasks* **on the old sever**.

9. Sync OpenStack
=================

To synchronize OpenStack objects run:

.. code-block:: bash

    fleio sync