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 - bundles with a docker-based structure. This article explores all the things you need to know about this feature.
# A shift from git-based bundles
If you've already built or used bundles with Entando, you should know that before Entando 7.1, the bundles were git-based. That means the source code (or project) and the build artifact (the deployable bundle) were stored in 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 this. 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 set 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 the component definitions 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 the Keycloack configuration for local usages | svc/ The auxiliary service folder, such as Docker compose files and the 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, contents, page templates… One sub-folder per component type |
If you'd like to make an in-depth comparison between these implementations, our documentation provides a table here.
The CLI and commands are now using the docker-based structure, which can be created easily.
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:
(curl -sfL https://get.entando.org/cli) --update
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 should replace “my-bundle” with 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.
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 called "sample-ms" in the "microservices" folder 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.
First, edit the entando.json and update microservices/sample-ms to set the healthCheckPath and dbms properties:
{
"healthCheckPath": "/management/health",
"dbms": "postgresql"
}
Next, 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.
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 appropriate to your environment.
You can run the "docker image ls" command to see your available images.
# 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 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.
# Deploy
This step is the same as for 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 the following command, where “entando” is the virtual machine name:
ent attach-vm entando
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:
When the deploying process is finished, you can navigate to your Local Hub by clicking on the “Hub” menu.
Then, you should see your bundle:
# 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
The micro frontends are now available in the App Builder to compose new pages. The microservices are pods and you can check them with the following:
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 and they are now docker-based. 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 in 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 that's also a new feature in 7.1 and this is the topic of the next blog post in this series. Stay tuned.