# Entando Bundle

The structure of an Entando Bundle leverages composable development methods, decoupling microservices, micro frontends, API management, and services such as databases. The ent bundle CLI module administers the process, using the descriptor entando.json. This single bundle descriptor defines all the components and resources of the docker-based bundle. The following page describes the descriptor, the structure, its conventions, and the building process.

The docker-based approach is an improvement on the previous Entando Bundle structure and to see the differences, refer to the Bundle Evolution page.

# Entando Bundle Conventions

  • There is a single bundle descriptor, entando.json, initialized and managed by the ent bundle CLI.
  • Microservices and micro frontends can be built independently, each with their own folders.
  • The platform directory is dedicated to platform specific components such as fragments, pages, and static resources. For more information on component types and descriptors, see the Bundle Component Details page.
  • The svc directory is allocated for auxiliary services and the docker-compose configuration files that define them. The ent bundle module enables, starts and stops the services. MySQL, PostgreSQL, and Keycloak services are available with Entando out of the box, and for more details, go to the ent CLI Services page.
  • Optionally, a thumbnail for your bundle can be set by adding a JPG or PNG image file to the bundle root folder. The file must be named "thumbnail" and be 100kb or less, e.g. thumbnail.png.

# Project Structure

   bundle-project/
  .git/
  .entando/  <= An internal working folder for caches, logs, and build artifacts
    config.json    
    output/
      descriptors/
    logs/
      microservices/
      microfrontends/
  microservices/   <= Source and build output for each microservice
    ms1/    
    ms2/   
    ms3/       
  microfrontends/  <= Source and build output for each microfrontend
    mfe1/   
    mfe2/   
    mfe3/   
    mfe3-config        
platform/     <= platform specific components    
    pageTemplates/
      page-template.yaml
    pages/  
  svc/     <= auxiliary services for local development 
    keycloak.yaml
    ...         
  entando.json    <= project bundle descriptor
  thumbnail.jpg   <= bundle thumbnail

Note: For a full list of platform components, see the Bundle Component Descriptors page.

# Bundle Development Process

Bundle Development Process

The ent bundle CLI module manages the building and publishing of an Entando Bundle. From initialization to installation, from adding MFEs and MSs to calling for services such as Keycloak and making API claims, the ent bundle commands streamline the development process.

At initialization, the project scaffolding is built. A project can be started from scratch with this structure or retrieved interactively from an Entando Hub as a starting point for new bundles. Microservices, micro frontends, components, services, and API claims can then be added. At this stage, components can be run locally and independently with the ent bundle commands.

The next steps build and pack the project using the bundle descriptor. The specifics depend on the component type and stack. The build phase constructs the microservices and micro frontends while the pack command generates the artifacts and Docker images. Images are built for the bundle and for each microservice.

In the publish step, images are pushed to a Docker registry and tagged according to the bundle configuration. A custom registry can also be used.

Bundle Publishing Process

Finally, the bundle is deployed into the Local Hub of a running Entando instance where it can then be installed. Any improvements to the bundle can be made by repeating the four steps: pack, publish, deploy and install. Alternatively, the install step can be done in the App Builder UI by the composer designing the application.

At every phase of the process, options are available to fine-tune the process, and to see more information, go to the ent bundle CLI documentation.

# Bundle Descriptor entando.json

The following is a list of specifications for the bundle descriptor and its component parts.

# Bundle Descriptor Specifications

Name Type Required Description
name String Yes The bundle project name used as the default Docker image name
description String No A description of the bundle project shown in the App Builder
version String Yes The bundle version used as the default Docker image tag
displayName String No A descriptive label used in the UI in place of a name
global Global[] No Global bundle configuration items
microservices Microservices No Bundle microservices
microfrontends Micro Frontends No Bundle micro frontends
{
  "name": "my-bundle-name",
  "description": "my bundle description",
  "type" : "bundle",
  "version": "0.0.1",
  "svc": [
        "keycloak"
    ]
}

# Microservices Specifications

Name Type Required Possible Values Description
name String Yes Microservice name
stack Enum Yes *spring-boot
*node
*custom
Microservice stack
dbms Enum No *none^ *embedded *postgresql *mysql DBMS required by the MS to provide services
healthCheckPath String No Endpoint for a health check
ingressPath String No Custom ingress path for health check
deploymentBaseName String No Used to define custom pod names
permissions Permission[] No List of permissions to grant to the microservice
roles String[] No Exposed security roles
env EnvironmentVariable[] No Required environment variables
Microservices Environment Variables No Entando-provided env variables for MS
commands Command[] No Custom command(s) definitions
version String Required only for a custom stack Microservice version override

^ dbms none: Oracle and other DBMS types are not supported for automatic deployment in a container. Bundle env variables should be used instead, similar to connecting the EntandoApp to an external database.

# Microservices Sample Code

"microservices": [
    {
      "name": "my-ms",
      "stack": "spring-boot",
      "dbms": "mysql",
      "healthCheckPath": "/management/health",
      "ingressPath": "/ingress",
      "roles": ["admin"],
      "env": [
        { "name": "SIMPLE_VAR",
          "value": "mySimpleValue" 
        },
        { "name": "SECRET_VAR",
          "secretKeyRef": {
              "name": "YOUR-BUNDLE-ID-my-secret", 
              "key": "mySecretKey"
          }
        }
      ]
    }
  ]

# Microservices Details

  • Entando recommends that REST APIs be added to microservices.

  • To utilize environment variables, inline or based on Kubernetes Secrets, see the Plugin Environment Variables tutorial.

  • Entando uses the healthCheckPath to monitor the health of the microservice. A plugin in an Entando Bundle can use any technology, as long as it provides a health check service configured via the healthCheckPath. This path must be specified in the descriptor file and return an HTTP 200 or success status. This can be implemented by a Java service included with the Entando Blueprint in the Spring Boot application. You can also use a Node.js service as shown here (opens new window).

# Micro Frontends Specifications

Name Type Required Possible Values Description
name String Yes Micro frontend name
stack Enum Yes *react
*angular
*custom
MFE stack
type Enum Yes *widget *widget-config *app-builder Type of MFE
category String No Default is User For widget type only, any custom name (See below)
slot Enum Yes for type=app-builder *primary-header *primary-menu *content Named reference to an App Builder embedded position in a specific layout
paths String[] Yes for type=app-builder and slot=content App Builder activation paths
titles String[] Yes for type=widget Localized widget labels
group String Yes Visibility group name
publicFolder String No Default is public MFE public folder (typically where index.html is located)
apiClaims String[] No See API Claim spec below
nav MenuEntry[] No Bundle menu global links
commands Command[] No Custom commands definitions
buildFolder String No Default is build Corresponds to the MFE build folder
configMfe String No The custom element for the corresponding widget-config MFE
params MfeParam[] Yes User configuration for executing a widget
contextParams String[] Yes Information extracted from the application context
version String Required only for custom stack MFE Microfrontend version override

# Configure a Path for Static Assets

To configure your micro frontend with access to static assets, Entando provides two paths, one for widgets and another for EPCs.

  • For widgets: window.entando?.widgets['YOUR-MFE']?.basePath;

  • For EPCs: window.entando?.epc['YOUR-EPC']?.basePath;

See the instructions for setting the path in a React MFE.

# Custom Category

A custom category provides an organizing classification for Widgets, to appear as a separate grouping in the App Builder Page Designer. A custom category can only be used with MFEs of the type widget. All widgets or MFEs will appear under User Widgets unless a custom category is specified.

# Micro Frontends Sample Code

 "microfrontends": [
    {
      "name": "my-mfe",
      "stack": "react",
      "titles": { "en": "My MFE Title", "it": "Il Mio Titolo MFE" },
      "type": "app-builder",
      "category" : "My custom category",
      "slot": "content",
      "paths": ["/path1"],
      "group" : "free",
      "apiClaims": [...]
    },
    {
      "name": "my-mfe2",
      "stack": "custom",
      "type": "widget",
      "publicFolder": "public",
      "titles": { "en": "My MFE2 Title", "it": "Il Mio Titolo MFE2" },
      "group": "free",
      "commands": {
          "build": "echo 'Please edit this command to customize the build phase' && exit 1",
          "run": "echo 'Please edit this command to customize the run phase' && exit 1",
          "pack": "echo 'Please edit this command to customize the pack phase' && exit 1"
      },
      "version": "0.0.1"
    }
   ]

# API Claim Specification

Name Type Required Possible Value Description
name String Yes Name
type Enum Yes *internal *external Category of claim, either inside the same bundle (internal) or same namespace (external)
serviceName String Yes The name of the microservice
serviceUrl String No The URL of the microservice deployed in the local environment
bundle String Yes only for type=external Bundle Docker URL

# API Claim Spec Sample

 "apiClaims": [
   {
     "name": "int-api-claim",
     "type": "internal",
     "serviceName": "my-ms"
   },
   {
     "name": "ext-api-claim",
     "type": "external",
     "serviceName": "my-ext-bundle-ms",
     "bundle": "registry.hub.docker.com/my-organization/my-ext-bundle-ms"
   }
 ]

For more information, go to the API Management page.

# Command Specification

Name Type Required Description
build String No Custom build command
run String No Custom run command
pack String No Custom pack command

# Command Spec Sample Code

  "commands": {
    "run": "mvn -Dspring-boot.run.arguments=\"--server.port=8082\" spring-boot:run"
  }

Depending on the stack type, default values are:

  • build: mvn test, npm run test
  • run: mvn spring-boot:run, npm run start
  • pack: mvn package, npm run build

# EnvironmentVariables Specification

Name Type Required Description
name String Yes Name of the env variable to inject
value String No Value to give to the env variable
secretKeyRef SecretKeyRef[] No A reference to a secret

# Microservices Environment Variables

The following are platform-provided runtime variables.

Name Type Description
KEYCLOAK_REALM string Keycloak or Red Hat Single Sign-On (RH-SSO) realm to be used by the MS.
KEYCLOAK_AUTH_URL string Keycloak/RH-SSO URL to be used by the MS.
KEYCLOAK_CLIENT_SECRET secretKeyRef[] Keycloak/RH-SSO autogenerated clientSecret to be used by the MS.
KEYCLOAK_CLIENT_ID secretKeyRef[] Keycloak/RH-SSO autogenerated clientId to be used by the MS.
SERVER_SERVLET_CONTEXT_PATH string Context path used to access the MS. Automatically handled by a Spring Boot MS, but can be manually set for other stack types.
SPRING_PROFILES_ACTIVE string Application profile to use when the MS runs on Entando, differentiating dev vs prod at runtime. Automatically handled by a Spring Boot MS but can be manually managed if using another technology stack.
SPRING_DATASOURCE_URL string Provisioned database JDBC connection URL. Automatically handled by a Spring Boot MS but can be manually managed if using another technology stack.
SPRING_DATASOURCE_USERNAME string Provisioned database username. Automatically handled for a Spring Boot MS, but can be manually managed if using another technology stack.
SPRING_DATASOURCE_PASSWORD string Provisioned database password. Automatically handled for a Spring Boot MS, but can be manually managed if using another technology stack.

# Global Specification

Name Type Required Possible Values Description
nav MenuEntry[] No Bundle menu global links
Name Type Required Possible Values Description
label String[] Yes Localized entry in the PBC menu
target Enum Yes *internal *external Where to open the menu link
url String Address of the page to open when the menu is clicked

# MfeParam Specification

Name Type Required Description
name String Yes Name of the parameter
description String No Description of the parameter
  "params": [
      {
        "name": "username",
        "description": "username of user"
      },
      {
        "name": "description",
        "description": "description of user"
      }
  ],
  "contextParams": [
      "page_code"
  ]

# Permission Specification

Name Type Required Description
clientId string Yes The clientId of the other MS this MS needs access to
role string Yes The role required on the OIDC client of the service that the MS needs access to

# SecretKeyRef Specification

Name Type Required Description
name String Yes The secret name
key String Yes The secret key inside the secret object