# Build and Publish a Simple Bundle

# Overview

This tutorial shows you 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 your bundle artifacts into git, apply the Entando bundle custom resource to Kubernetes, and then installing the bundle into your application.

# 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, an available git repository, and an Entando instance.

Some of the following steps can be simplified by using the ent prj command and its publication system (pbs) convenience methods. The manual steps are also provided in those cases.

# Create the project structure

First create a parent project directory along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files also live under the parent directory.

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

# Add a simple widget

Create a widget directory and descriptor file:

mkdir widgets
touch widgets/example-widget.yaml

Populate the example-widget.yaml with a simple definition. Make sure to retain the correct YAML indentation.

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 descriptor.yaml is the main file processed by the Entando Component Repository and describes all of the components in the bundle. The name of the bundle descriptor must be descriptor.yaml.

touch descriptor.yaml

Populate the descriptor with the following YAML definition:

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

The component descriptor file name and location (e.g. widgets/example-widget.yaml) are arbitrary since the bundle descriptor explicitly points to the file. The typical convention is to group components by type, for example with all widgets in one directory, all page templates in another, etc.

# Publish the bundle

You can publish a bundle using the CLI or you can perform the steps by hand.

# 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. You'll need the git repository URL and your credentials here.
ent prj pbs-init
  1. Publish the bundle to git. By convention your first version will be v0.0.1 but this is up to you.
ent prj pbs-publish

On subsequent iterations you can run just this command again to quickly push a new version of your bundle to git.

  1. You can now create the custom resource for your bundle and apply it to Kubernetes in one step. You should modify the target namespace parameter (-n) if you changed it from the default.
ent prj generate-cr | ent kubectl apply -n entando -f -

The generate-cr command uses the git repository URL and project name from earlier steps to create the custom resource.

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

# 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 using the following commands.
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.0

Next generate the custom resource for your bundle. Run the entando-bundler from-git command and 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

Next 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 via kubectl get EntandoDeBundle -n entando

# Install the bundle into an application

Now you can go to the App Builder → Component Repository and install your bundle. You should see your bundle in the list and when you click Install you can select your preferred version if the bundle contains more than one.

At this point the Entando platform will download and install the components contained in the bundle. Once complete you should see the Install button change to give you an option to Uninstall that specific version. You can also navigate to Components → Micro Frontends & Widgets and find your custom widget under the User section.

← Build and Publish a Project Bundle →