Explore Docker-based bundles with JHipster and Entando 7.1

At Entando we define a bundle as a package that contains one or more components. A bundle can be a single component, component collection, PBC, or solution template, based on the level of granularity. Any bundle built with Entando is an Entando Bundle. Entando 7.1 introduces a major new change for bundles with a Docker-based structure. This article explores all the things you need to know about that feature.

Anthony Viard - Monday, December 19, 2022
Tags: Community

At Entando we define a bundle as a package that contains one or more components. A bundle can be a single component, component collection, PBC, or solution template, based on the level of granularity. Any bundle built with Entando is an Entando Bundle.

Entando 7.1 introduces a major new change for bundles with a Docker-based structure. This article explores all the things you need to know about that feature.

A shift from Git-based bundles

If you’ve already built or used bundles with Entando, you should know that before v7.1, the bundles were Git-based. That means the source code (called project) and the built artifact (the deployable bundle) were stored under two different Git repositories.

Traditionally, the source code repository is used by the Creators team for coding and building components with development tooling. The coding flow is similar to what we find in any development team, pushing and merging branches to share and review the code within the team.

The second repository stores the result of the compiling process, the artifact, that Curators can register in a hub, and Composers can install on their Application Composition Platform.

The Docker-based bundle is a total shift from that point. The source repository is still present but, all the artifacts are now sent to a Docker registry using Docker images.

A structure modification

The publishing process was improved with the tool change, so we took the opportunity to streamline the bundle structure itself.

We have a more readable and consistent bunch of folders with the Docker-based bundles.

Git-based Docker-based
bundle/descriptor.yaml

The main bundle descriptor

entando.json

The main Entando file that contains components definition and metadata

ui/

The micro frontends sources folder

microfrontends/

Centralized micro frontends folder

src/

The backend sources folder

microservices/

The microservices folder, one per component

src/main/docker

The auxiliary service folder such as Docker compose files and Keycloack configuration for local usages

svc/

The auxiliary service folder such as Docker compose files and Keycloack configuration for local usage

*.sh

Shell script used by the CLI to compile and build the bundle

platform/

The folder for any Entando related component such as pages, content, page templates… One sub-folder per component type

If you like to make a deep comparison between these implementations, our documentation provides a table here.

This means that the cli and commands are now following that structure and you can easily run them to create a new one.

Let’s start a new project to discover this

Create a new 7.1 bundle with the ent CLI

Prerequisites

Before moving forward, you have to ensure that your Entando CLI is up to date. If not, please run the following command:

bash <(curl -sfL https://get.entando.org/cli) --update
image7.png

Don’t forget to activate it with the following command

source "$HOME/.entando/activate"

Initialize the project

From your favorite folder, run the following command to initialize the project.

ent bundle init my-bundle

Please note you can replace “my-bundle” according to your project name.

A new folder is created with this project name; open it as a project with your favorite IDE to check the new structure.

image4.png

You can check the entando.json file content, and the metadata:

{
   "microservices": [],
   "microfrontends": [],
   "svc": [],
   "name": "my-bundle",
   "version": "0.0.1",
   "description": "my-bundle description",
   "type": "bundle"
}

Add a microservice

In the project folder, run the following command to add a new microservice.

ent bundle ms add sample-ms --stack=spring-boot

We specify the stack because of the dedicated metadata we may need with some stack types. This command creates a new folder, sample-ms, in microservices and adds an entry in the entando.json.

{
   "microservices": [
       {
           "name": "sample-ms",
           "stack": "spring-boot",
           "healthCheckPath": "/api/health"
       }
   ],
   "microfrontends": [],
   "svc": [],
   "name": "my-bundle",
   "version": "0.0.1",
   "description": "my-bundle description",
   "type": "bundle"
}

Please note this new folder is empty and you have to add your own code. We provide an easy way to start; let’s do it with JHipster.

Call JHipster with the following commands

cd microservices/sample-ms
ent jhipster --blueprints=entando

Then, select only the default values.

When the generation is done, the sample-ms folder contains all the files provided by JHipster.

Customize the bundle for JHipster

You just need to tweak a couple of things to make it work properly.

  1. Edit the entando.json and update microservices/sample-ms to set the healthCheckPath and dbms properties:
   "healthCheckPath":"/management/health",
   "dbms":"postgresql"
  1. Move the Blueprint-provided auxiliary service definitions into the svc directory in the bundle project:
    mv microservices/sample-ms/src/main/docker/* svc/

This enables the ent CLI to start Keycloak:

ent bundle svc enable keycloak

For advanced use cases, you can add MFEs with this tutorial. Please note that for microservices, you have to execute some extra steps.

Discover the new publishing process

This new bundle structure comes with a simpler publishing process provided by new streamlined CLI commands.

You can find a graphic of the different steps below. It describes the overall process and helps you to understand the details involved in every step.

image6.jpg

Let's follow it for our new 7.1 bundle.

Build

From the root project folder, run the following command:

ent bundle pack

Please note, you need to have Maven installed for this to execute. You also need Docker installed; you can check the installation procedure here regarding your environment.

image4.png

You can run the docker image ls command to see your available images.

image5.png

Publish

Once it’s finished, run the next command to publish the bundle to a Docker repository.

ent bundle publish

In this step, you need to be logged into the Docker hub, ensure you have an account or create a new one on this website: https://hub.docker.com

Please note, you can decide to publish the images to another registry by providing the URL with the --registry parameter.

image1.png
image10.png

Deploy

This step is the same as the previous Entando version, even if the commands have been modified to keep the consistency. Here, you need to have an available running instance of Entando. Visit https://developer.entando.com to install a local one.

Please note that you need your ent CLI profile to be connected to your Entando instance. If you followed the previous steps and installed a local multipass VM, you might have to run this command: ent attach-vm entando where “entando” is the virtual machine name.

Otherwise, it is possible to attach a kubeconfig file with this: ent attach-kubeconfig {kubeconfig-file}.

From your bundle root folder, run the following command:

image2.png

When the deploying process is finished, you can navigate to your Local Hub by clicking on the “Hub” menu.

image8.png

Then, you should see your bundle.

image3.png

Install

As you can see, the bundle is available in your Local Hub but not installed yet. That means nothing is running on your cluster from that bundle and the components are not available for composition.

To install them, you can use the UI and click on the install button in the Local Hub or, you can run the following command from your bundle root folder: ent bundle install

image9.png

The micro frontends are now available in the App Builder to compose new pages. the microservices as pods and you can check them with ent kubectl get pods -n entando.

Conclusion

In this article, we discovered a few new features provided by Entando 7.1. The bundle structure has been rebuilt; they are now docker-based and the publishing process has been optimized with the ent CLI commands. The JHipster blueprint has been optimized to match this new paradigm.

You can find explanations of these features during our 7.1 live with Sohini.

Did you know the bundle we just created can be used like a template to create a new one? Maybe not, because it’s also a new feature on 7.1 and this is the topic of the next blog post in this series. Stay tuned.

Modernizing Applications?

Learn how an Application Composition Platform can help.

Fast, customizable, easily scalable: these are the three main features that your web application must have if you want it to be a real competitive advantage for your company.

DOWNLOAD
Entando_WhitePaper.png