Welcome to Entando

None

This document contains release notes for Entando 5.0.1.

Library and dependency updates

Security updates

Swagger

REST API Definition

Red Hat Process Automation Manager (PAM) plugin

Authentication and Authorization Model

App Builder

CMS

Some dependencies in 5.0.1 still reference snapshot versions of components and other related products. This will be resolved in 5.0.2.

Versioning Information

This document contains release notes for Entando 5.0.

These release notes highlight new features in Entando 5.0, list features that are in technical preview, and include any known issues.

The goal of Entando 5.0 is to fully engage our platform with the Modern Applications revolution by designing for a cloud-based infrastructure, adapting our architecture to be more distributed, and fully supporting DevOps methodologies.

Entando 5 represents a fundamental update to the Entando infrastructure to support modern application development processes including: new options for clustering, cloud native deployment, out of the box support for deploying apps in OpenShift, new UI technologies, and an updated widget development process.

These release notes provide a technical introduction to the changes included in Entando 5. Check out our Installation guide, Getting Started guide, or our blog for examples and more on putting Entando 5 to work.

Entando is a built to be a very light framework requiring limited runtime resources. When extending Entando in a development setting, sizing for development environments that add to an Entando install is up to individual user requirements.

Prerequisites:

>>>>>>>>ADD CONFIGURING BPM HERE FOR RH VERSION<<<<<<<<<<

Set up an Entando application via a Maven archetype. The archetype creates the project and structure needed to develop and add to an application.

Steps:

Full Stack Example Images

The project below includes scripts and example images that will boot up a full stack of Entando apps in Docker. https://github.com/entando/entando-ops/tree/master/Docker/Production/entando-full-stack

These projects are useful to quickly boot up an Entando environment in Docker. Can be forked/cloned for extension and updates as needed as well. Scripts and image names can be seen in the repository

Base Image

This base image provides a base Dockerfile that can be extended to create and manage an Entando application. The base image downloads all of the maven dependencies required for an application to run so the initial run can take some time however after that edits to a child Dockerfile will run fast. The base example in the Readme uses a jetty/derby combination for execution

https://github.com/entando/entando-ops/tree/master/Docker/Production/builder-images/docker-builder-5

Using S2I to Build Docker Images

To use the Docker S2I images, you must have already set up a database. See the Setting up a Database section for details.

By default, the app deployed in Docker will connect to a Postgres database to persist resources created using the App Builder and by the MApp Engine. In the app created from the archetype, update the properties in: <your application>/.s2i/environment to point to the user and databases created in the Setting up a Database section.

After configuring the database:

Run the Image

docker run -d -p 8080:8080 <your image name>

The app may take some time to start. It is downloading maven dependencies at startup. Your app will be available on http://localhost:8080/<your_project_name>; after startup is complete.

By default the image exposes port 8080 however you can change the local port mapped to that value by editing the first instance of 8080 in the docker run command above.

With Entando version 5.0 the Admin Console has been redesigned and renewed with the adoption of the PatternFly framework and guidelines. PatternFly is built on top of Bootstrap3 and provides an enterprise grade UX look and feel based on research and UX best practices.

The Page Tree subsection shows the hierarchical structure of the pages and their statuses, and lets you perform all page management actions.

The Page Configuration section is where you assign widgets to the frames defined by the Page Model you applied to your page. The available widgets are in the right pane. Apply widgets by dragging and dropping them to a frame of your choice.

This is also where you publish or unpublish the page or preview the layout prior to publishing.

Click the Info button for a summary of options you assigned when creating the page, e.g., Title and Owner Group.

A Widget is an independent software component configured and executed within your application’s page. Widgets provide UX/UI blocks that deliver a specific function.

Fragments are single portions of front-end interface used in widgets (including plugins) and Page Models. They are are HTML blocks that include Freemarker instructions by using specific tags that you replace with appropriate values each time you use the fragment. Entando then renders the widgets using the fragments. The FRAGMENTS section lets you manage existing fragments or add new ones.

The Page Model is the look and feel of an application’s page. It defines the structure of the page using frames or areas of the page that contain widgets.

Entando lets you set restrictions on users (see Figure below), specifically a shelf life for passwords and a maximum time between log ins before the password expires.

The Data Types section lists all available Data Types, their attributes, and is where you can create a new data structure.

Categories are dividers and parent folders for pages in your Entando page tree. Add a new category by clicking the Add button.

The Languages tab displays a list of all configured languages in the system. You can add as many different languages to the system as you need by selecting a language from the Select Language drop down menu and clicking Add. You can then include the appropriate vocabulary for any term in the System Labels section.

The System Labels tab displays system labels that apply to the entire Entando application. By default, system labels are available in English and Italian. If you add additional languages in the Languages tab, you can enter the appropriate word for a label in your choice language.

The Database section lets you back up your entire Entando’s database by clicking the Create Backup button. The backed up files become available from the Protected folder of the File Browser section once the backup process completes.

The File Browser section lets you browse files, upload, create text files and folders, and access database backups from two distinct areas of the file-system:

The Entando App Builder helps you create a variety of applications and integrate them with Red Hat BPM. It uses an intuitive UI, reusable templates, and drag-and-drop functionality that allows you to participate in every stage of the application design process regardless of your level of coding knowledge.

This demonstration walks through creating an applicant page for a mortgage application, and then integrates with Red Hat PAM.

Prerequisites:

The Applicant page is a public-facing webpage.

This document provides an introduction to using the Entando App Builder integrated with Red Hat Process Application Manager. This template application provides a page with a task list, task details, case comments (optional), and case management widgets (optional). The provided application can then be extended and customized using the App Builder functionality.

You can add images from the Digital Assets repository to content. When you do, the image comes with five image tags:

You have the option to manually assign values to these tags or automatically populate them with metadata values.

Once you have a digital asset in place, you have several editing and viewing options. Click the asset’s More Actions button and select "Edit" to update the asset’s name, location, and the file represented.

Starting with Entando 4.3.4, the platform has captured metadata for every image you have uploaded. View the metadata from the Images tab of the Digital Assets screen by clicking an asset’s Actions menu > Edit. The metadata appears in a table at the bottom of the screen.

See the Adding Images and Tags section for details on using image metadata in contents.

Beginning with Entando 4.3.5, you can crop images newly uploaded via Digital Assets. You can either crop the image dynamically or by using pre-configured crop ratios.

Click Done to exit the Edit screen.

You can also manually adjust metadata for an image in the Contents section.

You can exclude metadata fields by name by setting the following property in systemParams.properties: jacms.imgMetadata.ignoreKeys

For example:
jacms.imgMetadata.ignoreKeys=Blue TRC,Red TRC,Green TRC

You can customize the metadata fields displayed in the Resource Metadata Mapping section. By default, the values are Alt, Description, Legend, and Title, but you can add and remove fields.

Ensure that you have installed (mvn install) both Entando Core and Entando Components.

For database requirements, you need to make sure that you have a running DBMS (Postgres or MySQL) ready for installation.

Enter this in your command line: git clone https://github.com/entando/entando-pwa.git

After cloning, you will notice that there are two folders inside entando-pwa which are "pwa-provider" and "pwa-shell". Go inside "pwa-provider" and follow the next steps.

This section will give you a quick guide on installation and running the provider instance.

1. CREATING DATABASE

PWA provider includes Ant tasks for you to use first-hand without the need to setup database manually. Refer to the Developers' guide on configuring Ant and executing afterwards. In default, this system is being setup on a Postgres database environment, so make sure you indicated your preferred database by modifying it in "pwa-provider/buildproperties.xml".

For the sake of this procedure (and a possibility that you may have installed PostgreSQL), you can try running ant PG-db-create under "pwa-provider" to install the postgres database.

2. SETUP PWA PROVIDER SYSTEM PARAMETERS

This has been configured to use Keycloak Authentication, but in this guide, we will be using the default Entando authentication included in the provider instance. So to make sure you have configured the authentication type properly, you need to check on "pwa-provider/src/main/config/systemParams.properties" and see at the end of the line configuration that the keycloak mode is not enabled. Check the line with keycloak.enabled has been set to false.

3. RUNNING THE INSTANCE

Using the console, and still under "pwa-provider" folder, just simply enter this command line: mvn jetty:run to launch the PWA Provider instance. First time launching the instance can take a little more time because of dependency installations.

When you see these lines in the console:

This means your provider instance is ready. You can access this with the URL http://localhost:8080/pwa-provider using your web browser. This is basically the same interface from your Entando Core Instance. Please refer to CMS on setting up and publishing your content.

Now this guarantees that your provider is up and running, it’s now time to setup your PWA-powered web app!

This section will provide you quick steps on installing your Entando-powered Progressive Web App.

1. INSTALL NPM DEPENDENCIES

The very first thing you need to do is install the app’s module dependencies by going into pwa-shell folder and running npm install (or npm i). This may take a while, so maybe grab a coffee or you can proceed on configuring your environment variables.

2. CONFIGURE .ENV VARIABLES

Before launching the app, you need to ensure that the environment variables are correct. When you open ".env" file under "pwa-shell" folder, you will see variables being preconfigured. For local environment, you should create a file named ".env.local" and enter the following variables:

3. LAUNCH THE APP

Run the command npm start in pwa-shell folder to launch your app in development mode and you should see the app opened in your web browser as http://localhost:3000. Perfect!

4. APP DEPLOYMENT

Run command npm run build to build production-level files that will reside under "build" folder after the build process. There are different server platforms to choose to host your app. Visit https://facebook.github.io/create-react-app/docs/deployment for more information on deployment.

For this feature, you will need to install and launch Docker (https://www.docker.com/). Make sure that your PWA provider and PWA shell are not running as of this point.

This section will provide you extra steps on activating Keycloak authentication feature.

1. INSTALL ENTANDO KEYCLOAK PLUGIN

Run git clone https://github.com/entando/entando-keycloak-plugin.git on your terminal console to grab our plugin that is needed in PWA Provider later on. After downloading using git, go in by running cd entando-keycloak-plugin and then run mvn install -DskipTests to maven install Entando Keycloak plugin. It won’t take long to finish the process.

2. LAUNCH DOCKER INSTANCE

Going back to the pwa-provider folder, you should see docker-compose.yml file. This will be used to create and launch the keycloak instance. Make sure your Docker is ready, go to console (and pwa-provider folder, of course), run docker-compose up and this will begin launching the instance. For first time, this will take time because of downloading dependencies. You might see these similar lines in your launch console:

This means your keycloak instance is ready. Open http://localhost:8081 into your web browser and you should see this screen:

3. CONFIGURE KEYCLOAK

This section will give you a walkthrough on how you should setup your realm, client ID and other configurables.

To begin with the last screen shown, click "Administration Console" and you will be brought to a login screen. Provide our usual login credentials:

And now you should be inside the Keycloak admin console.

Navigate to the top left of the screen, under the Keycloak logo, you should see a dropdown with the default realm name master. Below the dropdown, there’s a button labeled Add realm. Click that button.

This will only ask for the name of the realm. For this guide, we shall name this as "entando-development". Click Create to proceed.

Afterwards, this will prompt you to fill more details on your new realm. You don’t need to touch those. Moving on to next.

When you look at the navigation again, you should be seeing "Clients" menu.

Click on that then this will bring you to list of Clients for your realm. With this, we need to create two clients named "entando-app" and "entando-pwa".

Click "Create" button on top right of the list to begin.

For the first entry, give the client an ID with entando-app. Then click Save.

Now on the Client details form and under Settings tab,

After saving, go to the Credentials tab and should see the secret key. Take note of the secret key because we’re going to use this later on under the PWA shell configuration.

Now go to Roles tab, then it should show that there are no client roles available. You must add the roles into the list. Click the Add Role button on top right to start adding the following roles (with patience):

After that, go to Service Account Roles tab and go to the lower right where you can see the Client Roles dropdown and select "realm-management". On right you should see a menu list that you can add to the Assigned Roles list. Choose "realm-admin" and press Add selected to add realm-admin to the Assigned Roles.

Now you’re done with entando-app client. But you need to add one more, which is "entando-pwa". On the left nav, click Clients again and go to the rightmost side and click Create.

For the second entry, give the client an ID with entando-pwa. Then click Save.

Now for the details form and under Settings tab, do the following:

And that should be it for the Clients section.

This should be pretty quick for this section. This is for demo purposes only since we don’t want to use OTP in the local environment, we should disable it. So going to the Authentication settings on the left nav, under Flows tab, open the dropdown (with HTTP Challenge in it) and change it to Browser. At the bottomost part of the table, you should see a field OTP Form. Choose "Disabled" and you’re done.

If you wanted to test its user access capability, we need to create a user. On the left nav, go to Users and on the (supposedly empty) user list, press Add User at the right side of it.

Give it a username, and some basic information. For this guide, We’ll use "admin" as the username and other basic information you see on the screenshot below, then hit Save button.

Lastly, you need to set its password. Go to Credentials tab and fill out its new password and make sure to switch Temporary field to "off". Then press Reset Password button to set the password.

Now you have finally finished configuring your Keycloak instance. Time for us to go back to your PWA Provider and configure it with Keycloak!

You should be in your pwa-provider in your terminal console. Locate again pwa-provider/src/main/config/systemParams.properties and open it. We need to reconfigure the Keycloak settings. See again at the end part of the file and change the ff:

Save it. and then run mvn jetty:run in your console to launch your PWA Provider instance. This should go well if you have followed the procedure on setting up Keycloak.

We need to tell the app that we are now using Keycloak authentication for user management and security. Go now to pwa-shell folder and open .env.local to make changes on the environmental variables:

REACT_APP_AUTH_TYPE is now "keycloak" and we add two variables named REACT_APP_KEYCLOAK_REALM with your realm name "entando-development" and REACT_APP_KEYCLOAK_CLIENT_ID with "entando-pwa" for this is the 2nd client we created back at Keycloak setup.

Don’t forget to save it. Then run command npm start to test it out.

This concludes your setup guide your Keycloak-powered Entando PWA!

There are 2 files we need to modify:

Modify them with same name and short_name you placed in the web app manifest file.

Your logo will be needed to represent your app (as an icon and splash screen when user starts your app). They will be needed once your app is being added to user’s device. These are already specified in your public/manifest.json. All you need to do is replace the icons using your own.

For the icons, there are two areas for you to modify:

This section will give you a quick guide on what are in-app image assets you can modify. Take note that all image assets you can find are inside pwa-shell/src/images folder.

Your App colors can be modified by changing SCSS variables under src/styles/variables.scss file. At the beginning of the file, you should see these lines:

The theme is consist of 5 representations:

All layout-related components are located in "src/ui" folder. It’s corresponding stylesheets (SCSS) are located in "src/styles" folder. Here are some essential files that are commonly known to modify for customisation:

API methods in this app are used with Entando’s API Manager going to specified PWA Provider instance. All related files are located inside pwa-shell/src/api folder. Here are the following files:

For more information on section details mentioned above, see CMS (Content Management System) for more details.

Entando PWA features a quick way to generate a language (JSON) file generator for the developer to easily customise. This is powered by react-intl with the efficient tools of react-intl.macro to extract messages around the app and followed by react-intl translations manager to gather all the extracted messages and place them all under one JSON file per language to efficiently let the developer translate the needed messages depending on your specified language.

Should you need to create or change the language, here are some steps for you to do:

You can set for the language by modifying languages array. You can have multiple languages if you want. For this example, we have indicated to use 'it' as your language.

For the example above, you have modified the message translations with 'it' (Italian) language.

for the example above, "it" language has been added to the list of locales.

Entando is a built to be a very light framework requiring limited runtime resources. When extending Entando in a development setting, sizing for development environments that add to an Entando install is up to individual user requirements.

Set up an Entando application via a Maven archetype. The archetype creates the project and structure needed to develop and add to an application.

Steps:

Enter the following commands in your command line:

This will give you a running app-builder instance using mock data. The Configuration section below covers connecting your App Builder to a running MApp engine.

There are two methods for using the App Builder, depending on whether the API calls will be to the live Entando Core or if they will use mock data.

If you set USE_MOCKS to "false," you must run an Entando Core (MApp Engine) instance and then to connect the App Builder to the MApp Engine using the following steps:

If you set USE_MOCKS to "true," you do not need to run the App Builder instance because you are only using mock data.

To connect the MApp Engine

To enable swagger in your development environment, you need to run your application with an enabled Swagger profile. There are two options. Run ONE of the following from the root of your generated project’s directory:

Default login details:
Username: admin
Password: adminadmin

Default Swagger OAuth details:
Type: Request Body
clientId: swagger
Secret: = swaggerswagger

The Swagger integration is based on three components and is activated by a Spring profile. The components are:

If the swagger Spring profile is active, Spring will initialize and wire all three components during application startup. If inactive, Entando ignores the components.

While it is theoretically possible to manage this multitude of Entando Docker containers using the 'docker' command, we strongly recommend using container management tools that allow you to manage multiple containers in concert. Entando itself is typically deployed on Docker in sets of two to three images. As containerization gains more traction in the industry, we expect more Entando Docker images to be added to these deployments. We therefor advise even the die-hard 'docker' command line users to familiarize themselves with one or more container management tool that allows you to easily deploy, start and stop multiple containers collectively using a single command.

Entando supports Docker Compose and Openshift, both of which simplify the management of multiple Docker containers and setting up connectivity amongst them. Since Entando Apps are still Java projects built with Maven, we have also added support for the Fabric8 Maven Docker Plugin for multiple Entando Docker images to be built built and tested during the development and build processes. We have developed quick starts for all three these technologies to make it easier for new users to get Entando up and running on Docker.

This demo was briefly discussed in the Getting Started section. The entando Full Stack demo deploys two images. Follow their links to read more about the image in question

This demo exports the standard ports of 5000 and 8080 to the Docker host. On Linux this would be localhost, but on Windows and Apple it will be the IP address of the virtual machine that hosts the Docker service.

The demo also allocates a local volume for the /entando-data volume. This volume contains the usual uploaded resources, protected and index files as described in the Common Volumes section. This particular configuration of the Entando Full Stack image comes with two pre-built embedded Derby databases that will be copied to the /entando-data/databases directory. Any changes made to the underlying database will therefore be persisted in this volume and will thus survive container restarts, even when the container itself is removed.

To determine the location of the volume, first list the volumes using docker volume ls and then describe the appropriate volume in more detail using docker inspect entando-full-stack_entando-volume. For Windows and Apple, keep in mind that those volumes are hosted inside the virtual machine that hosts the Docker service. If you want to clear the volume, stop the Docker containers and run docker volume rm entando-full-stack_entando-volume. This will reset all data stored in the volume.

Wherease the default confguration of the Entando Full Stack image uses the two embeded Derby databases, the configuration in docker-compose-postgresql.yml points Entando to an external database provided by our PostgreSQL. To run this demo, do the following:

The key difference between this demo and the Default Entando Full Stack demo is that the database here is hosted in a different container. For this reason, this demo requires two Docker volumes:

The first volume contains the usual uploaded resources, protected and index files as described in the Common Volumes section, but no database. The second volume contains the PostgreSQL database. If you want to reset the database, please delete this volume and let the PostgreSQL image recreate the database.

For more information on the individual images that this demo is composed of, follow these links:

The Entando team, Red Hat and our business partners have collaborated to bring you a demo that illustrates how Entando can be used as the user experience layer for your Red Hat Process Automation Manager processes. The process in question allows customers to initiate a dispute case against a specific transaction. This demo provides two Entando apps - a customer facing app and a back-office app. These apps connect to a shared KIE Server instance.

Both images in this demo come with their own embedded Derby databases. These databases are stored in the following Docker volumes

For more information about the images this demo is composed of, follow these links:

This demo is configured by default to use Entando’s public Red Hat PAM environment, where the necessary rules, processes and model objects have been pre-installed.

The scope and granularity of an Entando app play a significant role in designing the pipeline. By "scope", we need to look specifically at the organisational scope of the app, that is who it is that needs to work on the app. If several people in your organisation work on an Entando app, it is likely to be more coarse grained and your selected pipeline would look different compare to the pipeline of an Entando App that only has one or two developers working on it. This section offers some guidelines to decide what the best pipeline approach would be for your specific use case

Opting for a pure Openshift environment for your entire pipeline offers some significant benefits. You can manage and scale your build infrastructure as easily as you can manage and scale your deployment environments. You can scale out to a cloud provider if needed. You also have a centralized catalog of all pipeline related activity that is happening and there is definitely a benefit in reusing your Openshift knowledge for your build environment. On the negative side, one has to acknowledge that certain advanced build techniques that are not yet implemented in Openshift. It is also true that, whilst the Jenkins/Openshift integration already provides a viable option, there are still some features that are not fully integrated, which results in duplication and/or overlap that can be quite difficult to navigate. All in all though, this offers an appealing if perhaps slightly cutting edge option.

In a pure Openshift environment you are free to use the various build and deployment techniques described in its official documentation. Entando has also implemented a set of templates that would allow you to repeat and customize your configuration for various environments. If you want to take it one level further, we have a beta version of our reference pipeline based on the DevOps with Openshift book.

In a pure Openshift environment we would recommend that you leverage the three types of BuildConfigs that Openshift offers to build your Docker images: Source-to-Image builds, Dockerfile builds and Jenkins pipelines.

We will explore Entando’s offering in this space in more detail in the Entando on Openshift section

The hybrid Docker environment is common amongst customers that are growing from a more traditional continuous integration approach to a full DevOps approach. Such organizations often have mature continuous integration infrastructure from which it already benefits significantly. They may have evaluated Openshift’s build infrastructure but may have found it wanting on features that the organization already relies on, such as complex branch build algorithms required for pull requests. It could also be that the organization simply has skills primarily in Bamboo and that the move to Jenkins doesn’t seem like a cost effective step to take. Another motivation here could be that the organization is not using Openshift on Docker in the deployment environment, but some other container orchestration product that does not necessarily have Openshift’s out-of-the-box support for builds. The end result though is the same: the organization uses existing continuous integration infrastructure for all build related activities, and Docker is reserved primarily for the the deployment environment.

In hybrid Docker environments, it is best to think of the Docker image as the unit of delivery that is handed off from the build environment to the Docker environment. It almost serves the same role as tradition JEE war files did in the days of monolithic application servers. Like a JEE war file, the traditional build infrastructure therefore produces and verifies the Docker image, and the publishes it to a shared artifact repository, in this case a Docker registry. During deployment to a shared environment, the deployment process then picks up the Docker image and instantiates it with the correct environment variables in the target environment.

We would recommend using the Maven Docker plugin for these types of scenarios. It is a powerful build tool that allows you to produce the image immediately after the Entando war file is built. It does however require Docker capabilities on the Bamboo agent or Jenkins slave, even if it is just connected to a viable Docker server. This can be a bit tricky when the agent/slave is a Docker container itself, but it is certainly doable. Once the image has been built and verified, it can be handed off to any Docker based deployment environment. In fact, this makes the Maven Docker plugin very appealing for environments where the organization does not want to be tied into a specific container orchestration vendor, such as Openshift or Kubernetes. We will look into this option in the Maven and Docker section.

Central to building and running a Docker image from your Entando Maven project is the highly parameterized configuration of three 'image' elements in the Docker Maven Plugin, and a set of Maven profiles that instantiate this configuration in different ways. This section will briefly look at each 'image' element and the settings that were parameterized, and then look at the different profiles and the value of the abovementioned parameters in each profile. Ultimately, we would very much like for developers to be armed with the necessary information to chop and change the pom.xml to best suited for their development approach.

In the section Demos on Docker, we used Docker Compose to install Entando’s two pre-built demos. The pre-built images were configured using the standard 'docker-compose.yml' files. Openshift Templates fulfill a very similar role to docker-compose.yml files, and in fact can also be developed in the YAML format. Openshift Templates are used to configure the following objects that are used to build and deploy Docker images

Openshift Templates can be instantiated either from the commandline, or from the web-based Openshift Console. In the section on the Openshift Quick Start, we did in fact instantiate such a template, and we gave instructions on how to do so either from the commandline or from the web console. Please feel free to work through that example again, perhaps also exploring the Template definition file. Have a look at how the different objects we discussed above feature in this template.

When instantiating an Openshift Template, you also need to provide valid values for the Parameters in a Template. These parameter values are often passed on directly to one of the DeploymentConfigs as environment variables to the containers it manages. You will therefore often encounter one of Entando’s standard image environment variable in the form of an Openshift Template Parameter. There are also many Parameters in our templates that have exactly the same function in each of the Templates they occur in. This is in line with our container design philosophy that we like to keep things simple and consistent.

Entando’s two pre-built demos can be deployed to Openshift using a Templates built for these purposes. Refer back to the Openshift Quick Start on more detailed instructions on how to instantiate a Template. In this section we will focus primarily on the Parameters of the Template in question, and how the images are configured inside the Template' DeploymentConfigs. Remember to install the prerequisite ImageStreams in the Openshift project you have chosen for these purposes.

The first couple of Openshift examples illustrate how the end product of an Entando App can be deployed on Openshift in the form of pre-built images. However, Openshift also allows for the images to be built on the Openshift platform itself. In this section we will have a closer look at some of the Templates and S2I builder images that can be used to package and deploy your Entand App Image

The Entando Imagick S2I Image is the only image that can be used safely for environments where you require a shared CMS environment, and therefore the Entando Coarse Grained Apps use case. The reason for this is that it has the Imagick image manipulation package installed on Red Hat Linux. This package is required for uploaded images when it needs to be cropped or edited in other ways.

Please note that this configuration uses a child image of the official JBoss EAP commercial Docker Image. This would mean that in order to deploy this in a production environment, you would need to purchase the necessary subscription from Red Hat first.

Currently you need to install this image manually, as the Template to install this image is still under development. The image itself is also only a very basic extension of the original JBoss EAP image. Consider using it only if you are already familiar with the JBoss EAP image (https://access.redhat.com/containers/?tab=overview#/registry.access.redhat.com/jboss-eap-7/eap71-openshift). This image is also only available on Red Hat’s container marketplace (registry.connect.redhat.com)

Entando’s first reference Pipeline for Openshift based environments was based on Chapter 4 of the book DevOps with OpenShift which is available online at https://www.oreilly.com/library/view/devops-with-openshift/9781491975954/ch04.html. The overall architecture of this Pipeline is described quite accurately in the following diagram:

In thise 'Best Practices' Pipeline, all the projects run in the same cluster. All the CI/CD elements reside in a separate project depicted as the rectangle at the top of the diagram. The resulting Images are then published to ImageStreams in the Development project, depicted as a rectangle on the left. Note that, even though it does not preclude the use of an external Docker registry, all access to the Docker registry is mediated by the ImageStreams in the Development project. The remaining rectangles represent the Test and Production projects that contain similar deployment related objects to the Development project, but without the ImageStreams.

We have deviated slightly from this example pipeline. We decided to follow the more common pattern where the Openshift cluster responsible for CI/CD and testing is separate from the production cluster. We also opted for an external Docker registry which results in better support for build infrastructure outside of Openshift as well as better support for multiple clusters. Lastly, we have collapsed the Development and Testing environments into a single stage environment. We may support more complex deployment environments in future, but since Entando does most of the high risk work for you behind the scenes, we do not the typical fine grained app to carry such risk with it that it needs more than a single stage environment.

The overall architecture of the pipeline is as follows:

At the top, we have a project containing all the Jenkins Pipeline BuildConfigs. This project may or may not build the Docker images, as you will see later, but it definitely contains all the Jenkins Pipeline BuildConfigs. This is also the project from which the automatically provisioned Jenkins instance will be operating. For this reason, we also have to install ImageStreams in this project to make each of our Entando Jenkins Slave images available. Whoever has access to this project would be able to trigger a pipeline to either of the other two environments. In our pipeline, this project will carry the suffix "-build" to distinguish it from other projects in our application.

In the center of the image, we have an external registry. At Entando we use private Docker repositories running on Docker’s cloud infrastructure. You could opt to use other registries in your organization, such as the Nexus 3 Docker registry. It is also entirely possible to use Openshift’s built-in registry, although from the perspectivce of our BuildConfigs and DeploymentConfigs, it is still treated as an external Docker registry. This needs to be a secure registry. Your production evironment would be reading and deploying images from othis registry. Our deployment configs are setup to access this registry directly, rather than mediating through ImageStreams. Our pipelines would not benefit much from ImageStreams as we would not want deployments to be automatically triggered when an ImageStream is updated, and it would just add to the complexity of the deployment.

The project hosting the staging environment is depicted in the bottom left corner. This project only contains the necessary DeploymentConfigs, Services and Routes to expose your application. There are no BuildConfigs in this project. For our reference Pipeline, we decided to host both the EAP Image and the PostgreSQL image for the backing database in this project. It wouldn’t be too difficult to configure the EAP Image to point to an external database server, especially if you already have a clustered database server uup and running. However, for the purposes of the Fine Grained Apps use case it is unlikely that you would have massive scalability requirements on the database tier, especially since the vast majority of the data is read only, not updated, and Entando also provides you with a cluster safe cache in the form of the Infinispan plugin.

The project hosting the production environment is depicted in the bottom right corner. It is basically a mirror of the staging project, but you do have the option of increasing your pod replica count to meet your requirements in production. Other than that, the idea was to keep the staging and production projects as similar as possible. In fact, the reference pipeline installation script uses the same templates for both projects.

The installation script is contained in the file named setup-entando-pipeline.sh. This script takes a single command as a first parameter, and then any combination of arguments to follow in the format --arg-name=arg-value.

This concludes the overview of our generic Jenkins Pipeline infrastructure. At this point, you need to make a call whether your requirements would be best addressed with a Hybrid Docker Environment, or whether a Pure Openshift Environment addresses your need. Our reference Pipeline script supports both.

If you opt for an Openshift Only environment, your pipeline would look something like this:

As you can see, this Pipeline builds and pushes your Docker images to the external Docker registry. Under the hoods, it still uses S2I BuildConfig, but the process is controlled entirely from the Jenkins Pipeline. When promoting the resulting Image to one of the target deployment environments, this Pipeline follows the following process:

To install the entire pipeline, make sure that valid values have been given to all the variables in the configuration files. Then navigate to the Openshift/installers/reference-pipeline directory.

Once the references Pipelines have been installed, you can now trigger one of the builds. You will notice that there are the following seven different BuildConfigs.

If you opt for a hybrid environment, your pipeline would look something like this:

As you can see, this Pipeline needs your existing build infrastructure to build and pushe your Docker images to the external Docker registry. This Pipeline can then co-ordinate the promotion of the resulting Image to one of the target deployment environments, this Pipeline still follows the following process:

To install the entire pipeline, make sure that valid values have been given to all the variables in the configuration files. Then navigate to the Openshift/installers/reference-pipeline directory. Please note that each of the commands listed below includes the argument --promotion-only. This instructs the installation script to bypass the installation of any BuildConfigs or Pipeline steps that will actually build the Docker image.

Once the references Pipelines have been installed, you can now trigger one of the builds. You will notice that there are the following seven different BuildConfigs.

As you can see, these Pipelines all assume that the specified Docker Image has already been built. If you used our Maven archetype to generate your Entando App, it would be quite easy to introduce the necessary commands to achieve this. Please refer back to our Maven and Docker section for more details. Generally you would do the following: