66. Samples

66.1. devon4j My-Thai-Star Sample Application Template for Production Line

66.1.1. Introduction

Please read all of the following sections carefully.

66.1.2. Overview

This template will configure your PL instance to have a 'ready to use' My-Thai-Star devonfw application. It is only an example. In order to start a new project, please use the other templates. This includes:

  • Cloning the official My-Thai-Star (https://github.com/devonfw/my-thai-star) repository into your GitLab, which allows you to do customizations on your own.

  • Adding a build job for the Angular front-end, including a SonarQube analysis and a delivery to Nexus as zip and docker image.

  • Adding a build job for the Java back-end, including a SonarQube analysis and a deployment to Nexus as zip and docker image.

  • Adding a deployment job for the Angular front-end

  • Adding a deployment job for the Java back-end

  • Adding a deployment job for the reverse proxy. Please see My Thai Star deployment documentation

Especially the build and delpoyment jobs require several additional Jenkins plugins, which are not part of the PL by default. The Template will also take care of those installations.

All build and deployment jobs are taken from the official My-Thai-Star (https://github.com/devonfw/my-thai-star) repository. The created build and deployment jobs inside Jenkins will use the Jenkinsfiles from the cloned repo in Gitlab. These are currently the following Jenkinsfiles:

Jenkins Jobs
Table 44. Jenkins Jobs
Jenkins job name Path to Jenkinsfile in repo Description

MyThaiStar_FRONTEND_BUILD

jenkins/angular/cicd/Jenkinsfile

Builds and tests the Angular frontend. Pushes artifacts to Nexus.

MyThaiStar_SERVER_BUILD

jenkins/java/cicd/Jenkinsfile

Builds and tests the Java backend. Pushes artifacts to Nexus.

MyThaiStar_FRONTEND_DEPLOY

jenkins/angular/deployment/Jenkinsfile

Frontend deployment job. Downloads the docker images from Nexus3 and starts a new container usign that image.

MyThaiStar_SERVER_DEPLOY

jenkins/java/deployment/Jenkinsfile

Backend deployment job. Downloads the docker images from Nexus3 and starts a new container usign that image.

MyThaiStar_REVERSE-PROXY_DEPLOY

jenkins/deployment/Jenkinsfile

Reverse proxy deployment job. Downloads the docker images from Nexus3 and starts a new container usign that image. With this job you can also build the reverse proxy image.

66.1.3. How to report Issues

This template is independent from PL and devonfw releases and is also not really connected to one of the projects. Therefore issues that occur during the template setup or execution should be tracked in the issue section of this GitHub project.

66.1.4. How to contribute

In case you see improvements we would love to see a Pull Request.

66.1.5. Prerequisities before running the template

Production Line Components

To use the template you need to make sure that your PL has the following components installed:

  • Jenkins (required to run the template and to execute the build/deployment Jobs)

  • SonarQube (required for a static code analysis)

  • GitLab (required as a repostiory)

  • Nexus3 (required to store the build artifacts)

Tip

Additional components can be ordered from the ProductionLine service team.

Technical User Setup

In order to configure the services, we need technical users for the following components:

  • Gitlab

  • Nexus3

  • SonarQube

The following sections describe how to configure the components to enable technical users and tokens.

Manual configuration

In order to configure the Production Line components manually you can follow this guide

Automatic configuration

In order to configure the Production Line components automatically you can follow this guide

There is one thing that initialize-template can not do automatically: the gitlab token creation.

The creation of the GitLab Group and Project will require a private GitLab token which has to be created manually. The token can be obtained like this:

  1. Go to your Profile in Gitlab

500
  1. Next click on the pen icon

500
  1. On the left menu choose Access Tokens and put token name and check fields like below

600
  1. Click "Create personal access token", you should receive notification about created token and token string. Copy the token string.

600
Important

The GitLab API user needs to have API access and the rights to create a new group. To set this permission follow the next steps:

  1. Enter the Admin control panel

  2. Select 'Users'

  3. Select the user(s) in question and click 'Edit'

  4. Scroll down to 'Access' and un-tick 'Can Create Group'

Build/Deployment Requirements

The My Thai Star CICD pipelines will create a docker image and then the deployment pipelines will use it in order to deploy the application. As Production Line do not include a docker daemon, you need an additional server to do it. Those server needs:

66.1.6. How to run it

Warning

If Jenkins needs to install plugins, a restart will be performed. So please make sure, that nothing important is running.

Important

We have job-parameters inside the template Jenkinsfile that will only be active if Jenkins has run the job at least once!

Setup template job in Jenkins

The guide on how to add a template to your Jenkins can be found in the root directory of the template repository: https://github.com/devonfw/production-line.git

Execute the Jenkins job in your Jenkins
  • Go to the Jenkins job.

  • Execute job.

  • It will try to configure and setup the PL components such as Jenkins/Gitlab and Nexus.

Important

If a restart was needed, you need to trigger the job again!

  • The job should now show the required parameters, you only need to change the GITLAB PRIVATE TOKEN that you should have generated in the prerequisite section

600

When everything is "green" the template is done and you can have a look in the created "MTS" folder in Jenkins.

Important

It will take a few minutes to clone the official MTS repository to the internal Gitlab. So you need to wait before executing the build jobs at the frist time.

Build Jobs

You can now execute the build for the frontend and also the backend. They do not require any parameters to run. The expected result is, that both jobs can run without any errors. They will build, test and deploy the artifacts to Nexus3.

Deployment Jobs

All deployment jobs have several parameters configured in their Jenkinsfile. Unfortunately, Jenkins does not pick them up immediatly, so you need to execute the job once, by pressing the "Build now" button. The run should fail quite fast and once you refresh the page, the "Build now" button should have changed to "Build with Parameters". If you now click on the button you should see the parameters below:

Jenkins Deployment Parameters

You need to set the following parameters in order to get it running:

Table 45. Required Parameters
Parameter Description

registryUrl

The docker registry URL where image is stored.

registryCredentialsId

The nexus credentials to access to the docker registry.

VERSION

The version of the image that was built in the build jobs. For example "1.12.3-SNAPSHOT".

dockerNetwork

The docker network where the container will be deployed.

Also, the reverse proxy deployment has two more parameters:

Table 46. Reverse Proxy extra parameters
Parameter Description

buildReverseProxy

If true, it will build a new reverse proxy docker image and then deploy that image.

port

The port where the application will be listening. It’s a host port, not a container port.

Note

You can deploy multiple versions of My Thai Star in the same machine by changing the docker network in all deployments and the port in the reverse proxy deployment.

Important

You must choose the same docker network for all deployments

Important

You need to deploy the angular and java applications before the reverse proxy. Also, the first you need to check the buildReverseProxy parameter in order to create the reverse proxy image and then deploy the container.

Last updated 2021-03-17 08:55:56 UTC