Migrating application data
==========================

When you first start using Stackspin,
you probably already have data that you do not want to lose.
This guide will focus on a use-case
where you were already running the applications
that are included with Stackspin.
If you are migrating from different applications,
chances are you can still use similar methods to import the data into Stackspin-based applications.
For example, Zulip chat includes import functionality for
Mattermost, Rocket.Chat, Gitter and Slack.

Before you start any migration,
make sure you use a machine that has ``kubectl`` access to the machine
you want to recover Zulip on.
This is achieved by running the following on your provisioning machine:

.. code::

   export KUBECONFIG=$PWD/clusters/<your_cluster>/kube_config_cluster.yml``

Alternatively, you can run the commands from this guide in an SSH session
on the machine you run Stackspin on.

Also make sure you have already installed the apps you want to migrate.
Follow :ref:`install_additional_apps` if you have not done so yet.

Nextcloud
---------

To export and import your Nextcloud data into a Nextcloud running on Stackspin,
`follow the instructions in the Nextcloud documentation
<https://docs.nextcloud.com/server/latest/admin_manual/maintenance/migrating.html>`__.
There are a few things that go slightly differently,
because in Stackspin you need to run the commands through ``kubectl``.

In some commands, you need the Nextcloud pod name that you can get by running:

.. code::

   kubectl get pods -n stackspin-apps -l app.kubernetes.io/name=nextcloud

Note: the correct pod is the one that does not contain ``-cron``.

- In `the restore folders step
  <https://docs.nextcloud.com/server/latest/admin_manual/maintenance/restore.html#restore-folders>`__,
  instead of the command ``rsync -Aax nextcloud-dirbkp/ nextcloud/``,
  you need to use ``kubectl cp``:

  .. code::

     # replace nc-nextcloud-xxxxxxxxx-xxxxx with your NC pod name
     kubectl -n stackspin-apps cp nextcloud-dirbkp nc-nextcloud-xxxxxxxxx-xxxxx:/var/www/

  Note that ``kubectl cp``, unlike ``rsync`` does not overwrite directories.
  So you need to use ``kubectl exec`` into the pod to override the data directory.

  For example, you could run the following
  to backup the current Nextcloud ``html`` directory
  and overwrite it with your whole Nextcloud backup.

  .. code::

     kubectl -n stackspin-apps exec deploy/nc-nextcloud -it -- /bin/bash
     cd /var/www
     mv html html_backup
     mv nextcloud-dirbkp html

- In `the restore database step
  <https://docs.nextcloud.com/server/latest/admin_manual/maintenance/restore.html#restore-database>`__,
  follow the steps for MySQL (we use MariaDB, which is equivalent).
  Instead of running ``mysql $command``,
  run ``kubectl -n stackspin-apps exec nc-mariadb-0 -it -- mysql $command``.
  You can also ommit the ``-h [server]`` part,
  it will default to the correct server.

Go to https://files.stackspin.example.com
and log in using the *Log in with Stackspin* button.

Because Stackspin uses an OIDC provider,
it is likely that Nextcloud will not link the existing user
from your previous server to your Stackspin account.

If that happens, you can execute the following commands
to transfer your old files to your new account:

.. code::

   # Enter the Nextcloud container
   kubectl -n stackspin-apps exec deploy/nc-nextcloud -it -- /bin/bash
   # Change to the www-data user
   su -s /bin/bash www-data
   # Transfer ownership of your files to a new user
   php occ files:transfer-ownership <source-user> <destination-user>

   # You can use `php occ files:transfer-ownership --help` to find out more
   # about this command

Wekan
-----

Follow `the backup instructions on the Wekan wiki
<https://github.com/wekan/wekan/wiki/Backup>`__ to back-up your current Wekan
instance.

These restore instructions are based on the `Docker restore instructions
<https://github.com/wekan/wekan/wiki/Backup#restore-docker>`__,
but adjusted for Stackspin.
This guide assumes you have a MongoDB dump called ``dump`` in your current directory.

Copy the dump into the Wekan MongoDB pod:

.. code::

   kubectl cp dump stackspin-apps/wekan-mongodb-0:/bitnami/mongodb/data

Then, enter the mongodb pod, and execute the import command.
NOTE: this will remove all the data in your current Wekan instance.

.. code::

   kubectl exec -n stackspin-apps wekan-mongodb-0 -it -- /bin/bash
   cd /bitnami/mongodb/data
   wekan-db mongorestore --drop --dir=/data/dump

You should now be able to use Wekan with your old data on
https://wekan.stackspin.example.com.

WordPress
---------

To import an existing WordPress site into Stackspin, you will need:

- A database dump of your old website's database called ``dump.sql``.
- A copy of the ``wp-content`` folder
  (usually located on the server at ``/var/www/html/wp-content``)
  in a local directory called `wp-content`.

Make sure the copy of the wp-content directory and the database dump are made at
the same time.

We will go through the following steps:

1. Customize the WordPress installation in Stackspin
2. Import the Database
3. Import the files from wp-content

Customize the WordPress installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This is for users with Kubernetes experience only.
You can probably skip this step.

If necessary, you can override the following variables
to reflect your current site's configuration.
Follow the :ref:`system_administration/customizing:Customizing` guide in that case.

- Set ``DB_PREFIX`` to the database prefix that your current WordPress uses
  (default: ``wp_``)
- Set ``WP_VERSION`` to the version of your current WordPress site.
- Check if your current WordPress uses Redis.
  This is usually the case when you have the `redis-cache` plugin installed.
  If so, enable redis by setting `redis.enabled` to `true`.

After installing, check if your site is available at www.stackspin.example.com.

Import the database
~~~~~~~~~~~~~~~~~~~

Make sure to remove all explicit URLs to your site from the database.
If you host your site on ``example.com``,
WordPress tends to put links in the database as
``https://example.com/<link to your post>`` or
``http://example.com/<link to your post>``.
If you want to try this new deployment on a different domain,
that will cause problems.
To fix this, search for `https://example.com` in your database dump
and remove it, leaving only the relative URL ``/<link to your post>``.
Repeat this step for ``http://example.com``.

You need the WordPress database password. The easiest way to get it is to run:

.. code::

   helm get values -n stackspin-apps wordpress

And look for the value of ``database.auth.password``

Now, import your database dump with the following command:

.. code::

   kubectl exec -n stackspin-apps -i wordpress-database-0 -- mysql -uwordpress -p<your password> --database=wordpress_db < dump.sql

A breakdown of the command:

- ``kubectl exec`` means you want to execute a command in a container
- ``-n stackspin-apps`` uses the ``stackspin-apps`` namespace
- ``-i`` makes sure that ``stdin`` is passed to the container. This means that we
  can use ``< dump.sql`` to import the database export from your local system.
- We assume your database is running in a pod named
  ``wordpress-master-mariadb-master-0``.
- ``--`` tells kubectl to stop interpreting command line arguments as kubectl
  arguments
- ``mysql`` executes the ``mysql`` command in the container,
  with the following arguments:
  - ``-uwordpress`` sets the MySQL user to wordpress
  - ``-p`` provides the prassword of the ``wordpress`` user
  - ``--database=wordpress_db`` selects the ``wordpress_db`` database.
- ``< dump.sql`` reads the file ``dump.sql``
  and inserts it into the mysql command.
  Change this if your MySQL database dump has a different filename.


Import the files from wp-content/uploads
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Similar to how you would normally use ``scp`` to copy files to a server,
you can use ``kubectl cp`` to copy files to your wordpress pod.
Make sure wp-content/uploads does not contain a `.htaccess` file,
because one is mounted by this chart.

.. code::

   kubectl cp wp-content/ wordpress-master-0:/var/www/wp-content-mount

You'll have to change the ownership of the files to UID 33 (the `www-data` user in the WordPress container):

.. code::

   kubectl exec -it wordpress-master-0 -- chown -R 33:33 /var/www/wp-content-mount

Note: this will say
``chown: changing ownership of '/var/www/wp-content/uploads/.htaccess': Read-only file system``.
Don't worry, that's the mounted `.htaccess` file. All the other files' ownership *will* have changed.

Your WordPress site should now be available under https://www.stackspin.example.com

Zulip
-----

To migrate your data to Zulip, make an export of your existing Zulip server,
following
`the export instructions available here
<https://zulip.readthedocs.io/en/latest/production/export-and-import.html#data-export>`__.

To recover the data, we are going to follow
`the import instructions available here
<https://zulip.readthedocs.io/en/latest/production/export-and-import.html#import-into-a-new-zulip-server>`__,
except we are going to do a few things differently:

- Because Stackspin has already fully installed Zulip,
  instead of "Skipping step 3 during installation",
  we will remove the realm that the Stackspin installation creates.

- Do not edit ``settings.py`` in a Stackspin deployment of Zulip.
  That file is generated by the Zulip startup script.
  If you need to change any settings, refer to the
  :ref:`system_administration/customizing:Customizing`
  section of the documentation.

Copy your Zulip export to the Zulip pod by using ``kubectl cp``,
then enter a shell in your Zulip pod with ``kubectl exec``
(replace the filename with the name of your  export).

.. code::

   kubectl cp zulip-export-xxxxxxxx.tar.gz stackspin-apps/zulip-0:/home/zulip/deployments/current/
   kubectl exec -n stackspin-apps zulip-0 -it -- /bin/bash

Inside the pod, change to the ``zulip`` user
and access the current deployment folder.
Then unpack the zulip export ``.tar.gz``.

.. code::

   su zulip
   cd ~/deployments/current
   tar -xf zulip-export-xxxxxxxx.tar.gz

We start by removing the realm that was created by the Stackspin installation.
NOTE: If you have already used Zulip on Stackspin,
this will delete all the data!

.. code::

   ./manage.py delete_realm -r ''

The command will ask you to enter the name of the realm.
In our case, the name is an empty string, so just press enter.
Zulip should now say something like:

.. code::

   # Realm has been successfully permanently deleted.

Now, you can import the data from your Zulip export:

.. code::

   ./manage.py import '' zulip-export-xxxxxxxx