# Build and Publish a Simple Bundle

# Overview

In this tutorial you will learn how to create a simple Entando bundle and deploy it into the Entando Component Repository. This involves manually defining a bundle with a single widget, checking the bundle artifacts into Git, applying the Entando bundle custom resource to Kubernetes, and then installing the bundle into an application.

# Prerequisites

  • Use the Entando CLI to verify all dependencies for this tutorial are installed (e.g. Java, npm, Git).
ent check-env develop
  • Authenticated Git credentials, an empty Git repository and an available Entando instance are required for the commands below to execute without errors.

Publishing a bundle can be simplified by using the ent prj command and its publication system (pbs) convenience methods. Both the CLI and manual commands are provided.

# Create the project structure

First create a parent project directory (e.g. example-bundle) along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files live under the parent directory.

mkdir -p example-bundle/bundle; cd example-bundle/bundle

# Add a simple widget

Create a widget directory

mkdir widgets

Create a widget descriptor file within that directory

touch widgets/example-widget.yaml

Populate the widget descriptor file example-widget.yaml with a simple definition. Make sure to retain the correct YAML indentation of 2 or 4 spaces.

code: example-widget
titles:
   en: Example Widget
   it: Widget d'esempio
group: free
customUi: <h2>Hi from Example Widget</h2>

# Create the bundle descriptor

The main file processed by the Entando Component Repository is descriptor.yaml, which describes all of the components within the bundle. The name of the bundle descriptor file must be descriptor.yaml and it must be stored in the child bundle directory (e.g. example-bundle/bundle).

touch descriptor.yaml

Populate the bundle descriptor file with the following YAML definition

code: example-bundle
description: This is an example of an Entando bundle
components:
  widgets:
    - widgets/example-widget.yaml

Component descriptor file names and locations (e.g. widgets/example-widget.yaml) are arbitrary since the bundle descriptor explicitly points to those files. Convention is to group components by type with all widgets in one directory, all page templates in another, etc.

# Publish the bundle

The bundle can be published using the CLI or the steps can be performed manually.

# CLI steps

  1. Change to the project directory if needed
cd example-bundle
  1. Initialize the Entando project and accept the defaults
ent prj init
  1. Initialize the publication system. This step requires the empty Git repository URL (ending in .git) and your Git credentials.
ent prj pbs-init
  1. Publish the bundle to Git. By convention the first version is assigned the tag v0.0.1 but the prefix "v" is optional.
ent prj pbs-publish

Running just the command ent prj pbs-publish will quickly push subsequent iterations of the bundle to Git. You will be asked to input the bundle version each time. To ensure that iterations are listed in the correct order you must be consistent with versioning format and alphanumeric precedence.

  1. The bundle can now be deployed into the Entando Component Repository with one command
ent prj deploy

The prj deploy command uses the Git repository URL and project name (e.g. example-bundle) to create the custom resource.

  1. Jump to Install the bundle into an application to finish installing your bundle.

# Manual steps

  1. Change to the bundle directory if needed
cd example-bundle/bundle
  1. Run the following commands to initialize Git and commit the files
git init
git add .
git commit -m "Init Git repository"
  1. Add your remote repository as origin and push the bundle
git remote add origin https://your/remote/repository.git
git push -u origin master
  1. Publish a Git tag
git tag -a "v0.0.1" -m "My first tag"
git push --tags
  1. Now that you've published your bundle to Git you can create the Kubernetes custom resource for it.

Install the bundler if you haven't previously done so

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

To generate the custom resource for your bundle run the entando-bundler from-git command, then provide your remote Git repository URL via the --repository option and the correct namespace via --namespace. You can also provide a thumbnail for your bundle with --thumbnail-file or --thumbnail-url.

entando-bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml

Now you can apply this definition to Kubernetes. You may need to first transfer the file to your VM (e.g using multipass transfer).

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

You can confirm the presence of your custom resource with the command kubectl get EntandoDeBundle -n entando.

# Install the bundle into an application

Your bundle should appear in App Builder → Component Repository in your Entando instance. Clicking Install should allow version selection if your bundle has multiple iterations.

The Entando platform will then download and install the components contained in the bundle. Once complete you should see the Install button change to give you the option to Uninstall that specific version. If you navigate to Components → Micro Frontends & Widgets you should find your custom widget within the User section.

← Build and Publish a Project Bundle →