Self-Hosted: provide migration guide to help move from native to kubernetes

Author: glaubinix

docs/self-hosted/kubernetes-migration-guide.md

@@ -0,0 +1,144 @@
+# Migrating to Private Packagist Self-Hosted Kubernetes
+##
+
+## Requirements
+
+To start the migration process, your Private Packagist Self-Hosted Replicated Native instance needs to run version 1.12.5 or newer.
+To reduce the disruption to a minimum, we recommend that you set up your Private Packagist Self-Hosted Kubernetes
+instance on a different machine before you start the migration process.
+
+Please note that it is possible to install Private Packagist Self-Hosted Kubernetes on the same machine as your current
+Private Packagist Self-Hosted Installation. You can do so after you follow the instructions below to back up your existing data
+and before you start restoring the application data. However, the Private Packagist Self-Hosted installation process will uninstall
+certain components used by your current Private Packagist Self-Hosted installation. 
+
+## Backing up the data
+
+Private Packagist Self-Hosted uses three different storages. A PostgreSQL database used as primary storage,
+a Redis database used as secondary storage, cache, and job queue, and a file/blob storage for uploaded artifacts and dist
+files used during composer install.
+
+To avoid any data inconsistency and random errors during application usage all three of them need to be backed up and restored at the same time.
+
+Please note that you won't be able to restore Private Packagist Self-Hosted Kubernetes from snapshots created via Private Packagist Self-Hosted Replicated Native.
+
+### Stop the Private Packagist application
+
+```
+docker stop packagist-worker packagist-web packagist-repo
+```
+
+### Backup the dist and artifact files
+
+At the end of this step, you should have a `packagist_storage.tar.gz` file in your working directory.
+
+Please note that depending on the number of packages and versions used in your projects and the size of your dependencies
+it can take several minutes for this command to finish.
+
+```
+docker exec -it packagist-ui /srv/manager/bin/console packagist:self-hosted:migrate-storage export
+docker cp packagist-ui:/tmp/storage.tar.gz packagist_storage.tar.gz
+docker exec -it packagist-ui rm /tmp/storage.tar.gz
+docker stop packagist-ui
+```
+
+### Backup the PostgreSQL database
+
+At the end of this step, you should have a `packagist_db.sql` file in your working directory.
+
+```
+docker exec -it packagist-postgres pg_dump --clean --if-exists -U postgres -d packagist_db > packagist_db.sql
+docker stop packagist-postgres
+```
+
+### Backup the Redis database
+
+At the end of this step, you should have a `packagist_redis.rdb` file in your working directory.
+
+```
+docker exec -it packagist-redis /usr/local/bin/redis-backup.sh
+docker cp packagist-redis:/data/dump.rdb packagist_redis.rdb
+docker stop packagist-redis
+```
+
+### Start Private Packagist again (optional)
+
+Now that you have exported all the data, you may restart the Private Packagist application. This will allow your developers
+to continue with their work while you import the data in the Private Packagist Self-Hosted Kubernetes setup.
+
+```
+docker start packagist-postgres packagist-redis packagist-ui packagist-repo packagist-web packagist-worker    
+```
+
+Please note that any changes made in Private Packagist will now be lost and will have to be reapplied once everyone switches to Private Packagist Self-Hosted Kubernetes.
+
+## Installing Private Packagist Self-Hosted Kubernetes
+If you haven't done so already, now is the time to follow the [installation guide](./kubernetes.md) to install Private Packagist Self-Hosted Kubernetes.
+
+## Restore application data in Kubernetes
+
+All commands assume that you are logged in to the server where Private Packagist Self-Hosted Kubernetes is installed,
+your working directory contains the three files generated by the previous steps, and that
+Private Packagist Self-Hosted Kubernetes is installed in the Kubernetes namespace "default".
+
+To avoid any data inconsistency, we highly recommend going through the steps below in order and only restart the application
+once all the data has been restored.
+
+### Stop the Private Packagist application
+
+```
+kubectl scale deployment ui repo worker --replicas 0 -n default
+```
+
+### Restore the PostgreSQL database
+
+Follow the instructions below to restore the PostgreSQL database in the cluster.
+If you are using your own PostgreSQL instance, use the `packagist_db.sql` file directly to import the data into your instance.
+
+Please note that the backup will overwrite any existing data in the database and any changes you made during setup will be lost.
+
+```
+kubectl scale statefulset postgres --replicas 0 -n default
+kubectl delete pvc postgres-data-postgres-0 -n default
+kubectl scale statefulset postgres --replicas 1 -n default
+cat packagist_db.sql | kubectl exec -it -n default statefulsets/postgres -- psql -U postgres -d packagist_db
+```
+
+### Restore the Redis database
+
+Follow the instructions below to restore the Redis database in the cluster.
+If you are using your own Redis instance, use the `packagist_redis.rdb` file directly to [restore Redis from an RDB file](https://redis.io/learn/guides/import#restore-an-rdb-file) or follow the instructions of your hosted service provider.
+
+Follow these steps if you are using Private Packagist Self-Hosted with an embeded Kubernetes cluster
+```
+export PV_NAME=$(kubectl get pvc -n default redis-data-redis-0 -ojsonpath='{.spec.volumeName}')
+kubectl scale statefulset -n default redis --replicas 0
+rm /var/openebs/local/$PV_NAME/appendonly.aof
+cp packagist_redis.rdb /var/openebs/local/$PV_NAME/dump.rdb
+kubectl scale statefulset -n default redis --replicas 1
+```
+
+### Restore the dist and artifact files
+
+Please note that depending on the size of the `packagist_storage.tar.gz` file and the type of blob storage that you have configured
+it can take several minutes for this command to finish.
+
+```
+kubectl scale statefulset -n default ui --replicas 1
+kubectl cp -n default packagist_storage.tar.gz ui:/tmp/packagist_storage.tar.gz
+kubectl exec -n default ui /srv/manager/bin/console packagist:self-hosted:migrate-storage import /tmp/packagist_storage.tar.gz && rm /tmp/packagist_storage.tar.gz 
+```
+
+### Start the Private Packagist application
+
+Once your data has been restored. Restart the application, log in to Private Packagist, and verify that your organization
+and packages are there again.
+
+```
+kubectl scale deployment ui --replicas 1 -n default
+```
+
+### Adjust domain names
+
+In case you initially set up Private Packagist Self-Hosted Kubernetes with a different domain name, you can now edit the
+domain names in the Admin panel, if necessary adjust your DNS entries, and shut down the old Private Packagist Self-Hosted instance.