windup-openshift: Migration Toolkit for Applications on OpenShift

This project is useful if you want to try MTA on an OpenShift instance.
If you just want to test MTA using the images we have made available in the docker.io repository, go straight to the OpenShift template deployment section.
If you have made some changes to MTA and you want to test them on an OpenShift instance, in the next paragraph you'll find all the information for building your own docker images so that you're free to test your code.
There's also the case that you don't have an OpenShift instance available and, in this scenario, Red Hat Container Development Kit can help you working locally on your machine with any need for an OpenShift instance to test your changes to the code. In this case please follow the instructions in the Working with Red Hat Container Development Kit section.

OpenShift image construction

Install Docker

For building this project and creating Docker images you have to have a Docker instance running locally on your machine so that you can pull the built images.
Next you'll find some basic instructions to install Docker based on your local OS.

Install Docker for Fedora

1. Install Docker: $ sudo dnf install docker
2. Configure docker group (ref. Manage Docker as a non-root user):
   1. $ sudo groupadd docker
   2. $ sudo usermod -aG docker $USER
   3. Log out and log back in so that your group membership is re-evaluated
3. Test Docker is working: $ docker run hello-world

For any issue related to installation, you can refer to Docker documentation.

Install Docker for other OS

For any other platform you can follow the detailed instructions provided in the Install Docker guide from Docker.

Create an account to Docker Hub

You need an account on https://hub.docker.com in order to push your images and have them available in the docker.io repository.
So sign up yourself to Docker Hub at https://hub.docker.com taking care that the Docker ID you choose will be the <your_docker_id> value in the next steps.

Create a token on registry.redhat.io (only once)

1. Login on https://access.redhat.com/login
2. Go to Registry Service accounts
3. Create a New Service Account if you don't have one
4. Click on the service account and go to "Docker Login" tab.
5. Copy the bash command
6. Paste that command in a shell window on your local machine and execute it
7. Now your local Docker installation will have the credentials in ~/.docker/config.json

Create Docker images

1. Build this project: $ mvn clean install -Ddocker.name.windup.web=<your_docker_id>/windup-web-openshift -Ddocker.name.windup.web.executor=<your_docker_id>/windup-web-openshift-messaging-executor
2. Push images to docker hub:
   1. $ docker login
   2. $ docker push <your_docker_id>/windup-web-openshift
   3. $ docker push <your_docker_id>/windup-web-openshift-messaging-executor

If you want you can also set the tag for the built images (e.g. if you are working on a specific branch and you want to create images tagged with the branch name), you just have to add the tag name to the docker.name.windup.web and docker.name.windup.web.executor system properties' values (i.e. from the above example -Ddocker.name.windup.web=<your_docker_id>/windup-web-openshift:tag_value -Ddocker.name.windup.web.executor=<your_docker_id>/windup-web-openshift-messaging-executor:tag_value)

Point to your images

Now that your images are available on docker.io repository, you have to reference them in MTA template in order to use these images in the deployments.

1. open ./templates/src/main/resources/web-template-empty-dir-executor.json in an IDE or text editor
2. change all the "image" values to point to docker.io/<your_docker_id>/ instead of docker.io/windup3/

OpenShift template deployment

There are two different ways for deploying MTA on OpenShift based upon if you have cluster-admin privileges: if you have those privileges you can decide to follow Template deployment in OpenShift catalog (because you can operate on the default openshift project) or Import template in Openshift Web Console otherwise you can just go with the latter approach (Import template in Openshift Web Console)

Choose the template

There are different templates available to be imported in your OpenShift instance. The table below summarizes the different use cases for each template

Template	Requirements	Description
web-template-empty-dir-executor.json	OpenShift	The recommended template to deploy MTA on OCP The analysis data between the executor pod and the web console one are sent using REST web services
web-template-empty-dir-executor-shared-storage.json	OpenShift with ReadWriteMany (RWX) storage	This template deploys MTA on OCP using a shared storage between the executor pod and the web console one to share the analysis data

Template deployment in OpenShift catalog

1. login to Openshift: $ oc login
2. create the template: $ oc create -f ./templates/src/main/resources/web-template-empty-dir-executor.json -n openshift

Now, if you go to OpenShift Web Console home page, you'll see the Migration Toolkit for Applications (ref. screenshot-0) in the list of the available templates and so you can deploy it to a project just like any other template.

screenshot-0: in OpenShift Web Console (v3.7) Browse Catalog page you can see the Migration Toolkit for Applications 4.1 icon (4th row, 2nd column)

Import template in Openshift Web Console

1. copy the raw content of file web-template-empty-dir-executor.json
2. paste it in the "Import YAML / JSON" wizard in Openshift Web Console (ref. screenshot-1)
3. save and wait for the deployment to end

screenshot-1: in OpenShift Web Console (v3.7) Import YAML / JSON wizard you can paste template raw content

Working with Red Hat Container Development Kit

If you want to build locally your own images without the need to push them to the Docker repository, you can use Red Hat Container Development Kit (CDK).
"Red Hat Container Development Kit provides a pre-built Container Development Environment based on Red Hat Enterprise Linux to help you develop container-based applications quickly." (ref. Red Hat Container Development Kit documentation).
For installing CDK, please refer to the https://developers.redhat.com web site where you can find the Hello World! guide.
Once you have a fully working CDK instance, you can follow the next steps:

1. [optional]$ systemctl stop docker (do this only if you have Docker running on your machine)
2. $ minishift docker-env to display the command you need to type into your shell in order to configure your Docker client since the command output will differ depending on OS and shell type
3. execute the command from the step before
4. $ docker ps to test that it's working fine and you can see in output a list of running containers
5. $ oc login -u developer -p whatever to login to CDK OpenShift (the -p password parameter can really be whatever value you want for the developer pre-built user in the CDK)
6. $ docker login -u developer -p $(oc whoami -t) $(minishift openshift registry) to log into the CDK OpenShift Docker registry
7. $ mvn clean install -Ddocker.name.windup.web=$(minishift openshift registry)/$(oc project -q)/windup-web-openshift:latest -Ddocker.name.windup.web.executor=$(minishift openshift registry)/$(oc project -q)/windup-web-openshift-messaging-executor:latest to build the Docker images for this project with the right tags to push them to CDK OpenShift Docker registry
8. $ docker push $(minishift openshift registry)/$(oc project -q)/windup-web-openshift to push the image to the registry to create an image stream
9. $ docker push $(minishift openshift registry)/$(oc project -q)/windup-web-openshift-messaging-executor to push the image to the registry to create an image stream
10. now, before proceeding, you have to follow the above instructions about OpenShift template deployment
11. once you have successufully deployed, you can change the deployments to point to your local images.
    Go to Deployments web page and:
    1. choose mta-web-console deployment page
    2. select Actions => Edit from the top right button (ref.)
    3. check the Deploy images from an image stream tag box and select the values for the Image Stream Tag comboboxes selecting your project's name as Namespace, windup-web-openshift for Image Stream and latest for Tag
    4. push the Save button at the bottom of the page
    5. repeat these steps for mta-web-console-executor deployment using windup-web-openshift-messaging-executor as Image Stream combox value

Now your deployments are using the Docker images you have built locally on your machine and, whenever you update these images, new deployments will be triggered automatically when docker push command executes.

If you need more informations about how to interact with the CDK OpenShift Docker registry, please refer to the Accessing the OpenShift Docker Registry guide.