Build and Publish a Project Bundle

Overview

This tutorial shows you how to take an existing Entando project directory and deploy it to the Entando Component Repository. This involves building a Docker image from your microservice, creating your Entando bundle, checking your Bundle artifacts into git, and deploying the Entando bundle into Kubernetes.

The Entando CLI automates many of the tasks involved in deploying an Entando bundle but you can also choose to perform the tasks manually.

Prerequisites

• Use the Entando CLI to verify you have the prerequisites in place for this tutorial (e.g. Java, npm, git).

ent check-env develop 

• You will also need your git credentials, a git repository, and an Entando instance.
• You will also need an Entando project directory, either developed by hand or generated by the Entando Component Generator.

CLI Steps

The following steps make use of the Entando ent prj command and its publication system (pbs) convenience methods. See the Manual Steps section below for a more detailed description of the underlying tasks.

1. Build the project using the ent prj command. This saves you from having to build each part of the project individually. If you are using a project directory with just a bundle child directory (e.g. for a bundle exported from an environment or with hand-built components) then you should skip this step since there's nothing to build.

ent prj build

TIP

The first run can take longer due to node downloads for any MFE widgets. For later runs you can use ent prj fe-build or ent prj be-build to independently build just the frontend or backend components.

2. Initialize the bundle directory

ent prj pbs-init

3. Publish the build artifacts to github and Docker Hub.

ent prj pbs-publish

4. Create a Kubernetes custom resource and apply it to your Entando instance. You can modify the target namespace parameter (-n) if you changed it from the default.

ent prj generate-cr | ent kubectl apply -n entando -f -

5. Jump to the section below to finish installing your bundle: Install the bundle into your application

Manual Steps

Build Docker Image for Microservices

1. Build the project from the project directory

./mvnw -Pprod clean package jib:dockerBuild

Note

By default the organization used to generate the docker image is entando, but you can provide a custom value during project initialization, as well as by changing the pom.xml file or by providing the -Djib.to.image=<org>/<name>:<version> to the jib:dockerBuild command.

Note

Output image name is generated using the organization value defined during project initialization. You can override the provided values by altering the pom.xml file or by customizing the -Djib.to.image parameter used in the ./mvnw command

Warning

If you manually override the target image of the docker build, remember to update the plugin metadata in the bundle accordingly in the bundle steps.

2. View your image and tag

docker images

Output:

REPOSITORY               TAG                 IMAGE ID            CREATED             SIZE
myusername/example-app   0.0.1-SNAPSHOT      4ec7f05b2b27        33 seconds ago      213MB

3. Publish the Docker image to Docker repository (Docker Hub or equivalent). You may need to first login via docker login.

docker push <name-of-the-image:tag>

For example: docker push myusername/example-app:0.0.1-SNAPSHOT

Note

The first time your run this command it will have to push all of the layers. Subsequent runs will be much faster

Output:

 docker push myusername/example-app:0.0.1-SNAPSHOT
The push refers to repository [docker.io/myusername/example-app]
545361404af4: Pushed
...
f1b5933fe4b5: Pushed
0.0.1-SNAPSHOT: digest: sha256:804b3b91b83094c45020b4748b344f7199e3a0b027f4f6f54109cbb3b8a1f867 size: 2626

Build your bundle and publish to git

1. Populate the bundle with the generated micro frontends using ./buildBundle.sh or npm run populate-bundle.

./buildBundle.sh

Important The bundle population with the micro frontends requires some time to be processed. You should be able to follow the progress of the operation on the console.

2. The output of your bundle will be in the top level bundle directory in your microservice

3. Commit your bundle files to git, separate from the top-level project files.

echo bundle >> .gitignore
cd bundle/
git init
git add .
git commit -m "Init Git repository"

4. Create a new git repository and name it my-bundle (or a name of your choice).

5. Add your remote repository as origin and push the bundle.

git remote add origin https://your/remote/repository.git
git push -u origin master

6. Publish a git tag using the following commands.

git tag -a "v0.0.1" -m "My first tag"
git push --tags

7. Install the entando-bundler

npm install -g @entando/entando-bundler@6.3.0

8. Generate a custom resource for your bundle. You should provide your own bundle name, namespace, and repository URL.

entando-bundler from-git --name=<bundle-name> --namespace=entando --repository=<your-repository-url> --dry-run > example-bundle.yaml

9. Make your bundle available in Kubernetes

kubectl apply -f example-bundle.yaml -n entando

Install the bundle into an application

1. Log into the App Builder

2. Select Component Repository in the upper right

3. Find your bundle and select Install

At this point the Entando platform will download and install the Docker image for your microservice and install the micro frontends into the Entando application. You can add those micro frontend widgets to the page(s) of your choice.

You can use an Entando provided page or follow this tutorial to create your own page and/or page template. Please note that an application based on the Entando blueprint expects a user to be authenticated so you'll need to include the keycloak_auth UX fragment in your page template.