# Build and Publish a Simple Bundle

# Overview

This tutorial describes how to create a simple Entando Bundle and deploy it into the Entando Component Repository (ECR). This process consists of 4 essential steps:

  1. Define the bundle component(s)
  2. Check the bundle artifacts into a Git repository
  3. Apply the bundle custom resource to Kubernetes
  4. Install the bundle into an application

# Prerequisites

  • Verify dependencies with the Entando CLI: ent check-env develop
  • Authenticated Git credentials
  • An empty Git repository
  • A running Entando instance

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

  1. Create a parent project directory (e.g. example-bundle) and a child bundle directory:

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

    In a project generated by the Entando Component Generator (ECG), the microservice and micro frontend source files are stored in the parent directory.

# Add a Simple Widget

  1. Create a widget directory:

    mkdir widgets

  2. Create a widget descriptor file within that directory:

    touch widgets/example-widget.yaml

  3. Populate the widget descriptor file example-widget.yaml with a simple definition. 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

  1. In the child bundle directory, create a bundle descriptor file named descriptor.yaml:

    touch descriptor.yaml

    All of a bundle's components are defined within descriptor.yaml, which is the main file processed by the ECR.

  2. Add the following definition to descriptor.yaml:

    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 because 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 steps to publish a bundle can be performed manually or automated with the CLI.

# CLI Steps

  1. From the project directory, initialize an Entando project with default settings:

    ent prj init

  2. Initialize the publication system. This requires the URL of an empty Git repository (ending in .git) and your Git credentials.

    ent prj pbs-init

  3. 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

    To quickly push subsequent iterations of the bundle to Git, execute the ent prj pbs-publish command. Each push will prompt you to input the corresponding bundle version. You must be consistent with versioning format and alphanumeric precedence to ensure that iterations are listed in the correct order.

  4. Deploy the bundle into the ECR:

    ent prj deploy

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

# Manual Steps

  1. From the bundle directory, run the following commands to initialize Git and commit the files:

    git init
git add .
git commit -m "Init Git repository"

  2. Add your remote repository as origin and push the bundle:

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

  3. Publish a Git tag:

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

  4. Create the Kubernetes custom resource for your bundle:

    ent bundler from-git --name=example-bundle --namespace=entando --repository=https://YOUR-REMOTE-REPOSITORY.git --dry-run > example-bundle.yaml

    A bundle must be published to Git before you can create a custom resource for it. Provide the URL of the bundle's remote Git repository (ends with ".git"). To include a thumbnail for your bundle, use the option --thumbnail-file or --thumbnail-url.

  5. Transfer the file to your VM, e.g:

    multipass transfer example-bundle.yaml entando:

  6. Apply the bundle definition to Kubernetes:

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

  7. Confirm the presence of your custom resource:

    kubectl get EntandoDeBundle -n entando

# Install the Bundle into an Application

  1. In your Entando instance, go to App Builder → Component Repository

  2. Click Install. A bundle with multiple iterations allows version selection.

  3. Verify the Install button changes to Uninstall to indicate that the installation completed successfully

  4. Go to App Builder → Components → Micro Frontends & Widgets to confirm that your bundle appears in the "User" section

← Build and Publish a Project Bundle →