# Use Blueprint Generated Plugin and Micro Frontends Without a Bundle

# Objective

In this tutorial you will learn how to use the plugin and microfrontend generated using the Entando Blueprint in a running cluster without the need to include the components in a bundle.

If you haven't already generated a plugin and micro frontends with the component generator go here first Generate a Plugin

# Requirements

  • An Entando Plugin built with the Entando Component Generator and populated with micro frontends

  • Node and NPM are installed on your machine (use LTS version)

  • Docker is installed on your machine and you are able to upload images to docker-hub or an image repository of your choice

  • An installed instance of the Entando platform running Kubernetes. See Getting Started

# Steps

# 1. Generate a docker image for your microservice

JHipster uses the JIB Maven plugin to generate a docker image for your microservice.

The name of the output image generated with JIB will be composed by:

  • The organization you chose during the setup wizard (by default that's set to entando)
  • The name of the application
  • Version 0.0.1-SNAPSHOT

You can build the docker image with this command

./mvnw -Pprod clean package jib:dockerBuild

If for example during setup wizard you chose a custom organization myorg and the set the application name to jhipster the resulting docker image is going to be myorg/jhipster:0.0.1-SNAPSHOT

Note

The output image name can be changed in the pom.xml file by configuring the plugins.plugin.jib-maven-plugin.configuration.to.image tag

 <plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>jib-maven-plugin</artifactId>
   <configuration>
     <!-- ... -->
     <to>
       <image><!-- use a custom value here --></image>
     </to>
     <!-- ... -->
   </configuration>
 </plugin>

Note

Output image name can also be set by customizing the ./mvnw command using the -Djib.to.image parameter. For example, if you want to build an image with organization myneworg, name myapp and version latest you can do

 ./mvnw -Pprod clean package jib:dockerBuild -Djib.to.image=myneworg/myapp:latest

Warning

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

# 2. Publish the Docker image to Docker registry (DockerHub or equivalent)

Let’s now publish the docker image for the microservice to make it available later during bundle installation in the cluster.

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

# 3. Deploy the plugin into your Entando cluster

You can now deploy the plugin custom resource generated by the Entando Blueprint in the bundle/plugins folder.

Warning

As stated in step 1, if you changed the target image of your docker build, the plugin custom resource in the bundle/plugins folder needs to be updated to point to the correct image

From the jhipster project root

cd bundle/plugins

kubectl create -f <plugin-file.yaml> -n entando

# 4. Wait for your plugin to be in Running state and link the plugin with the app using an EntandoAppPluginLink custom resource

Once the plugin server deployment is up and running, you can create an EntandoAppPluginLink custom resource to make the plugin API available from the EntandoApp domain.

Here an example of a EntandoAppPluginLink custom resource. Some assumptions with this custom resource:

  • The EntandoPlugin generated with the blueprint is my-demo-plugin
  • The EntandoApp exposing the my-demo-plugin APIs is my-entando-app
  • Both are deployed on the entando namespace.
  • The link itself is named my-entando-app-to-my-demo-plugin-link
  • The name of the link yaml is my-link.yaml

Warning

Remember to change the fields to match your setup.

apiVersion: entando.org/v1
kind: EntandoAppPluginLink
metadata:
  name: my-entando-app-to-my-demo-plugin-link
  namespace: entando
spec:
  entandoAppName: my-entando-app
  entandoAppNamespace: entando
  entandoPluginName: my-demo-plugin
  entandoPluginNamespace: entando

Now add this link to your environment

kubectl create -f my-link.yaml -n entando

A new link deployer will start and will work behind the scenes to add your plugin ingressPath (this is part of the plugin spec) to the EntandoApp ingress

# 5. Upload the micro frontends to your Entando App

Now that the plugin and the app are linked together, you can proceed to generate the Micro Frontend from the App Builder and upload the static resources like js and css files.

  1. From AppBuilder go to Configuration -> File Browser and create a new folder inside the public folder and make the name of the folder the same as the name of the bundle (the value is in the code field available in the /bundle/descriptor.yaml file of the blueprint project) or using a custom name, e.g. demo-widget

Warning

If you choose to use a custom folder, remember to update the references in the customUI of the widget later

  1. Upload all the resources available in the /bundle/resources folder of the blueprint project into the folder you created above in the App Builder file browser.

Warning

You can decide to recreate the folder structure to be the same as the one in /bundle/resources or not, but you need to update the references in the customUI / configUI of the widget later if you choose a different folder structure.

  1. Create the widget. In the App Builder go to UX Patterns -> Widgets.

  2. Select Add

  3. Set whatever title you want

  4. For the customUI copy the one created in one of the widgets you generated from the blueprint. As an example, the customUI for the detailWidget of the conference entity is available in /bundle/ui/widgets/conference/detailsWidget/conference-details-widget.ftl

Warning

Remember to update all the references in the customUI to use the custom folder structure you defined

  1. Update the service url to match the location where you deployed the ingress for your microservice if you used a path different than the default. For example,
Update the service-url value with the relative path of your service if you're deploying a bundle
		Ex. <car-table service-url="/newBp/api"  />
	Or use the full path if you're deploying the BE and FE individually
		Ex. <car-table service-url="http://newbp-plugin-entando.192.168.64.7.nip.io/newBp/api"/>

Note

As of Entando 6.3 your Entando application will include a keycloak_auth fragment by default that will inject the token and connection to Keycloak that your microfrontends need to invoke protected APIs. You can see this token at UX Patterns -> Fragments in the App Builder and search for keycloak-auth.

  1. If you're creating a new page from scratch or your page is missing the Keycloak fragment you can add it with this freemarker snippet
<@wp.fragment code="keycloak-auth" escapeXml=false />

# 6. Use the microfrontend and microservice

You can now use your micro frontends and your microservice in your Entando App.

← How to setup a Nexus instance on a Kubernetes cluster →