From 3c5b657e8046612a8625ac10483e074a3d117c0c Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Wed, 3 Aug 2022 12:11:03 -0700 Subject: [PATCH 1/7] ENDOC-533 --- .../create/pb/publish-simple-bundle.md | 221 +++++++++--------- 1 file changed, 112 insertions(+), 109 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md index 475472a18b..0d6e9e8bf0 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md @@ -4,138 +4,141 @@ sidebarDepth: 2 # 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](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). 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. +This tutorial describes how to create a simple Entando Bundle and deploy it into the [Entando Component Repository](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). At minimum, this requires manually defining a bundle with a single widget, checking the artifacts into Git, applying the custom resource to Kubernetes, and then installing the bundle into an application. ## Prerequisites -* Use the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment) to verify all dependencies are installed (e.g. Java, npm, Git). -``` sh -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. +* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `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 -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](../../../docs/create/component-gen-overview.md), the microservice and micro frontend source files live under the parent directory. -``` sh -mkdir -p example-bundle/bundle; cd example-bundle/bundle -``` +1. Create a parent project directory (e.g. `example-bundle`) and a child `bundle` directory: + ``` sh + mkdir -p example-bundle/bundle; cd example-bundle/bundle + ``` + + In a project generated by the [Entando Component Generator](../../../docs/create/component-gen-overview.md) (ECG), the microservice and micro frontend source files are stored in the parent directory. ## Add a Simple Widget -Create a widget directory -``` sh -mkdir widgets -``` - -Create a widget descriptor file within that directory -``` sh -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. -``` yaml -code: example-widget -titles: - en: Example Widget - it: Widget d'esempio -group: free -customUi:

Hi from Example Widget

-``` +1. Create a widget directory: + ``` sh + mkdir widgets + ``` + +2. Create a widget descriptor file within that directory: + ``` sh + 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. + ``` yaml + code: example-widget + titles: + en: Example Widget + it: Widget d'esempio + group: free + customUi:

Hi from Example Widget

+ ``` ## 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`). -```sh -touch descriptor.yaml -``` - -Populate the bundle descriptor file with the following YAML definition -``` 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 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. +1. In the child bundle directory, create a bundle descriptor file named `descriptor.yaml`: + ```sh + 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`: + ``` 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 bundle can be published using the CLI or the steps can be performed manually. +The steps to publish a bundle can be performed manually or automated with the CLI. ### CLI Steps -1. Change to the project directory if needed -```sh -cd example-bundle -``` - -2. Initialize the Entando project and accept the defaults -``` sh -ent prj init -``` - -3. Initialize the publication system. This step requires the empty Git repository URL (ending in .git) and your Git credentials. -``` sh -ent prj pbs-init -``` - -4. Publish the bundle to Git. By convention, the first version is assigned the tag `v0.0.1`, but the prefix "v" is optional. -``` sh -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. You must be consistent with versioning format and alphanumeric precedence to ensure that iterations are listed in the correct order. - -5. The bundle can now be deployed into the Entando Component Repository with one command -``` sh -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. From the project directory, initialize an Entando project with default settings: + ``` sh + ent prj init + ``` + +2. Initialize the publication system. This requires the URL of an empty Git repository (ending in .git) and your Git credentials. + ``` sh + 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. + ``` sh + 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: + ``` sh + ent prj deploy + ``` + The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) to create the custom resource. Jump to [Install the Bundle into an Application](#install-the-bundle-into-an-application) to finish installing your bundle. ### Manual Steps -1. Change to the bundle directory if needed -``` sh -cd example-bundle/bundle -``` - -2. Run the following commands to initialize Git and commit the files -``` sh -git init -git add . -git commit -m "Init Git repository" -``` - -3. Add your remote repository as origin and push the bundle -``` sh -git remote add origin https://your/remote/repository.git -git push -u origin master -``` - -4. Publish a Git tag -``` sh -git tag -a "v0.0.1" -m "My first tag" -git push --tags -``` +1. From the bundle directory, run the following commands to initialize Git and commit the files: + ``` sh + git init + git add . + git commit -m "Init Git repository" + ``` + +2. Add your remote repository as origin and push the bundle: + ``` sh + git remote add origin https://your/remote/repository.git + git push -u origin master + ``` + +3. Publish a Git tag: + ``` sh + git tag -a "v0.0.1" -m "My first tag" + git push --tags + ``` + +5. Create the Kubernetes custom resource for your bundle: + ``` sh + 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`. + +6. Transfer the file to your VM, e.g: + ``` + multipass transfer example-bundle.yaml entando: + ``` + +7. Apply the bundle definition to Kubernetes: + ``` + kubectl -n entando apply -f example-bundle.yaml + ``` + +8. Confirm the presence of your custom resource: + ``` + kubectl get EntandoDeBundle -n entando + ``` -5. Now that you've published your bundle to Git, you can create the Kubernetes custom resource for it. - - Run the `ent bundler from-git` command, providing your remote Git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also include a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. - -``` sh -ent bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml -``` - -6. Apply this definition to Kubernetes. You may need to first transfer the file to your VM, e.g with `multipass transfer`. +## Install the Bundle into an Application -``` -kubectl -n entando apply -f example-bundle.yaml -``` +1. In your Entando instance, go to `App Builder` → `Component Repository` -7. Confirm the presence of your custom resource with the command `kubectl get EntandoDeBundle -n entando`. +2. Click `Install`. A bundle with multiple iterations allows version selection. -## 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. +3. Verify the `Install` button changes to `Uninstall` to indicate that the installation completed successfully -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. +4. Go to `App Builder` → `Components` → `Micro Frontends & Widgets` to confirm that your bundle appears in the "User" section From 456502cf48e7be69c174fec477fbb256cdd462bf Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Mon, 8 Aug 2022 16:49:43 -0700 Subject: [PATCH 2/7] ENDOC-533 Con't streamline and incorporating v5 --- .../create/pb/publish-simple-bundle.md | 58 +++++++++++++++---- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md index 0d6e9e8bf0..3aa359f2ca 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md @@ -4,9 +4,17 @@ sidebarDepth: 2 # 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](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). At minimum, this requires manually defining a bundle with a single widget, checking the artifacts into Git, applying the custom resource to Kubernetes, and then installing the bundle into an application. +This tutorial describes how to create and then deploy simple Entando Bundles into the [Entando Component Repository](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). Entando Bundles can be either git-based or docker-based. Despite differences in structure and protocol, the process to create any type of bundle can be partitioned into a 4-stage sequence: -## Prerequisites +1. Define the bundle component(s) +2. Check the bundle artifacts into a repository (Git or Docker) +3. Apply the bundle custom resource to Kubernetes +4. Install the bundle into an application + +The sections below detail the steps required to generate simple examples of each Entando bundle type. + +## git-based Bundles +### Prerequisites * Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` * Authenticated Git credentials * An empty Git repository @@ -14,7 +22,7 @@ This tutorial describes how to create a simple Entando Bundle and deploy it into 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 +### Create the Project Structure 1. Create a parent project directory (e.g. `example-bundle`) and a child `bundle` directory: ``` sh @@ -22,7 +30,7 @@ Publishing a bundle can be simplified by using the `ent prj` command and its pub ``` In a project generated by the [Entando Component Generator](../../../docs/create/component-gen-overview.md) (ECG), the microservice and micro frontend source files are stored in the parent directory. -## Add a Simple Widget +### Add a Simple Widget 1. Create a widget directory: ``` sh @@ -44,7 +52,7 @@ Publishing a bundle can be simplified by using the `ent prj` command and its pub customUi:

Hi from Example Widget

``` -## Create the Bundle Descriptor +### Create the Bundle Descriptor 1. In the child bundle directory, create a bundle descriptor file named `descriptor.yaml`: ```sh @@ -56,18 +64,18 @@ Publishing a bundle can be simplified by using the `ent prj` command and its pub 2. Add the following definition to `descriptor.yaml`: ``` yaml code: example-bundle - description: This is an example of an Entando 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 +### Publish the Bundle The steps to publish a bundle can be performed manually or automated with the CLI. -### CLI Steps +#### CLI Steps 1. From the project directory, initialize an Entando project with default settings: ``` sh ent prj init @@ -90,9 +98,9 @@ The steps to publish a bundle can be performed manually or automated with the CL ``` The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) to create the custom resource. -Jump to [Install the Bundle into an Application](#install-the-bundle-into-an-application) to finish installing your bundle. +You are now ready to [install the bundle into an application](#install-the-bundle-into-an-application). -### Manual Steps +#### Manual Steps 1. From the bundle directory, run the following commands to initialize Git and commit the files: ``` sh git init @@ -133,6 +141,36 @@ Jump to [Install the Bundle into an Application](#install-the-bundle-into-an-app kubectl get EntandoDeBundle -n entando ``` +You are now ready to [install the bundle into an application](#install-the-bundle-into-an-application). + +## docker-based Bundles + +* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` +* Authenticated Docker credentials +* A running Entando instance + +### Create the Project Structure + +1. TO-DO rework this step + +Initialize a new bundle based on a simple bundle in the Entando Cloud Hub: + + - To initialize the skeleton of a bundle project: + ``` + ent bundle init YOUR-BUNDLE-NAME + ``` + - To initialize a new bundle project via the Entando Hub: + ``` + ent bundle init YOUR-BUNDLE-NAME --from-hub --hub-url=https://entando.com/entando-hub-api + ``` + "will gather the bundle files from a bundle project under an Entando Hub bundle selected by user vs perform a new clean state bundle project by scaffolding default files and folders" + +### Add a Simple Microservice + +Build your bundle component(s) + + +You are now ready to [install the bundle into an application](#install-the-bundle-into-an-application). ## Install the Bundle into an Application 1. In your Entando instance, go to `App Builder` → `Component Repository` From ce8f7cba99c4f99a87bd757592da54834d8a6966 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 9 Aug 2022 08:39:55 -0700 Subject: [PATCH 3/7] ENDOC-533 Constrain to git-based, apply to 7.0 --- .../create/pb/publish-simple-bundle.md | 53 +--- .../create/pb/publish-simple-bundle.md | 230 +++++++++--------- 2 files changed, 129 insertions(+), 154 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md index 3aa359f2ca..900dd8823d 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md @@ -4,17 +4,16 @@ sidebarDepth: 2 # Build and Publish a Simple Bundle ## Overview -This tutorial describes how to create and then deploy simple Entando Bundles into the [Entando Component Repository](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). Entando Bundles can be either git-based or docker-based. Despite differences in structure and protocol, the process to create any type of bundle can be partitioned into a 4-stage sequence: + +This tutorial describes how to create a simple Entando Bundle and deploy it into the [Entando Component Repository](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). This process consists of 4 essential steps: 1. Define the bundle component(s) -2. Check the bundle artifacts into a repository (Git or Docker) +2. Check the bundle artifacts into a Git repository 3. Apply the bundle custom resource to Kubernetes 4. Install the bundle into an application The sections below detail the steps required to generate simple examples of each Entando bundle type. - -## git-based Bundles -### Prerequisites +## Prerequisites * Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` * Authenticated Git credentials * An empty Git repository @@ -22,7 +21,7 @@ The sections below detail the steps required to generate simple examples of each 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 +## Create the Project Structure 1. Create a parent project directory (e.g. `example-bundle`) and a child `bundle` directory: ``` sh @@ -30,7 +29,7 @@ Publishing a bundle can be simplified by using the `ent prj` command and its pub ``` In a project generated by the [Entando Component Generator](../../../docs/create/component-gen-overview.md) (ECG), the microservice and micro frontend source files are stored in the parent directory. -### Add a Simple Widget +## Add a Simple Widget 1. Create a widget directory: ``` sh @@ -52,7 +51,7 @@ Publishing a bundle can be simplified by using the `ent prj` command and its pub customUi:

Hi from Example Widget

``` -### Create the Bundle Descriptor +## Create the Bundle Descriptor 1. In the child bundle directory, create a bundle descriptor file named `descriptor.yaml`: ```sh @@ -71,11 +70,11 @@ Publishing a bundle can be simplified by using the `ent prj` command and its pub ``` 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 +## Publish the Bundle The steps to publish a bundle can be performed manually or automated with the CLI. -#### CLI Steps +### CLI Steps 1. From the project directory, initialize an Entando project with default settings: ``` sh ent prj init @@ -98,9 +97,7 @@ The steps to publish a bundle can be performed manually or automated with the CL ``` The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) to create the custom resource. -You are now ready to [install the bundle into an application](#install-the-bundle-into-an-application). - -#### Manual Steps +### Manual Steps 1. From the bundle directory, run the following commands to initialize Git and commit the files: ``` sh git init @@ -141,36 +138,6 @@ You are now ready to [install the bundle into an application](#install-the-bundl kubectl get EntandoDeBundle -n entando ``` -You are now ready to [install the bundle into an application](#install-the-bundle-into-an-application). - -## docker-based Bundles - -* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` -* Authenticated Docker credentials -* A running Entando instance - -### Create the Project Structure - -1. TO-DO rework this step - -Initialize a new bundle based on a simple bundle in the Entando Cloud Hub: - - - To initialize the skeleton of a bundle project: - ``` - ent bundle init YOUR-BUNDLE-NAME - ``` - - To initialize a new bundle project via the Entando Hub: - ``` - ent bundle init YOUR-BUNDLE-NAME --from-hub --hub-url=https://entando.com/entando-hub-api - ``` - "will gather the bundle files from a bundle project under an Entando Hub bundle selected by user vs perform a new clean state bundle project by scaffolding default files and folders" - -### Add a Simple Microservice - -Build your bundle component(s) - - -You are now ready to [install the bundle into an application](#install-the-bundle-into-an-application). ## Install the Bundle into an Application 1. In your Entando instance, go to `App Builder` → `Component Repository` diff --git a/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md index 475472a18b..900dd8823d 100644 --- a/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md @@ -4,138 +4,146 @@ sidebarDepth: 2 # 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](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). 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. +This tutorial describes how to create a simple Entando Bundle and deploy it into the [Entando Component Repository](../../../docs/getting-started/concepts-overview.md#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 + +The sections below detail the steps required to generate simple examples of each Entando bundle type. ## Prerequisites -* Use the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment) to verify all dependencies are installed (e.g. Java, npm, Git). -``` sh -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. +* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `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 -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](../../../docs/create/component-gen-overview.md), the microservice and micro frontend source files live under the parent directory. -``` sh -mkdir -p example-bundle/bundle; cd example-bundle/bundle -``` +1. Create a parent project directory (e.g. `example-bundle`) and a child `bundle` directory: + ``` sh + mkdir -p example-bundle/bundle; cd example-bundle/bundle + ``` + + In a project generated by the [Entando Component Generator](../../../docs/create/component-gen-overview.md) (ECG), the microservice and micro frontend source files are stored in the parent directory. ## Add a Simple Widget -Create a widget directory -``` sh -mkdir widgets -``` - -Create a widget descriptor file within that directory -``` sh -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. -``` yaml -code: example-widget -titles: - en: Example Widget - it: Widget d'esempio -group: free -customUi:

Hi from Example Widget

-``` +1. Create a widget directory: + ``` sh + mkdir widgets + ``` + +2. Create a widget descriptor file within that directory: + ``` sh + 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. + ``` yaml + code: example-widget + titles: + en: Example Widget + it: Widget d'esempio + group: free + customUi:

Hi from Example Widget

+ ``` ## 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`). -```sh -touch descriptor.yaml -``` - -Populate the bundle descriptor file with the following YAML definition -``` 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 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. +1. In the child bundle directory, create a bundle descriptor file named `descriptor.yaml`: + ```sh + 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`: + ``` 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 bundle can be published using the CLI or the steps can be performed manually. +The steps to publish a bundle can be performed manually or automated with the CLI. ### CLI Steps -1. Change to the project directory if needed -```sh -cd example-bundle -``` - -2. Initialize the Entando project and accept the defaults -``` sh -ent prj init -``` - -3. Initialize the publication system. This step requires the empty Git repository URL (ending in .git) and your Git credentials. -``` sh -ent prj pbs-init -``` - -4. Publish the bundle to Git. By convention, the first version is assigned the tag `v0.0.1`, but the prefix "v" is optional. -``` sh -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. You must be consistent with versioning format and alphanumeric precedence to ensure that iterations are listed in the correct order. - -5. The bundle can now be deployed into the Entando Component Repository with one command -``` sh -ent prj deploy -``` - The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) to create the custom resource. - -Jump to [Install the Bundle into an Application](#install-the-bundle-into-an-application) to finish installing your bundle. +1. From the project directory, initialize an Entando project with default settings: + ``` sh + ent prj init + ``` + +2. Initialize the publication system. This requires the URL of an empty Git repository (ending in .git) and your Git credentials. + ``` sh + 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. + ``` sh + 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: + ``` sh + 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. Change to the bundle directory if needed -``` sh -cd example-bundle/bundle -``` - -2. Run the following commands to initialize Git and commit the files -``` sh -git init -git add . -git commit -m "Init Git repository" -``` - -3. Add your remote repository as origin and push the bundle -``` sh -git remote add origin https://your/remote/repository.git -git push -u origin master -``` +1. From the bundle directory, run the following commands to initialize Git and commit the files: + ``` sh + git init + git add . + git commit -m "Init Git repository" + ``` + +2. Add your remote repository as origin and push the bundle: + ``` sh + git remote add origin https://your/remote/repository.git + git push -u origin master + ``` + +3. Publish a Git tag: + ``` sh + git tag -a "v0.0.1" -m "My first tag" + git push --tags + ``` + +5. Create the Kubernetes custom resource for your bundle: + ``` sh + 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`. + +6. Transfer the file to your VM, e.g: + ``` + multipass transfer example-bundle.yaml entando: + ``` + +7. Apply the bundle definition to Kubernetes: + ``` + kubectl -n entando apply -f example-bundle.yaml + ``` + +8. Confirm the presence of your custom resource: + ``` + kubectl get EntandoDeBundle -n entando + ``` -4. Publish a Git tag -``` sh -git tag -a "v0.0.1" -m "My first tag" -git push --tags -``` - -5. Now that you've published your bundle to Git, you can create the Kubernetes custom resource for it. - - Run the `ent bundler from-git` command, providing your remote Git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also include a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. - -``` sh -ent bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml -``` - -6. Apply this definition to Kubernetes. You may need to first transfer the file to your VM, e.g with `multipass transfer`. +## Install the Bundle into an Application -``` -kubectl -n entando apply -f example-bundle.yaml -``` +1. In your Entando instance, go to `App Builder` → `Component Repository` -7. Confirm the presence of your custom resource with the command `kubectl get EntandoDeBundle -n entando`. +2. Click `Install`. A bundle with multiple iterations allows version selection. -## 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. +3. Verify the `Install` button changes to `Uninstall` to indicate that the installation completed successfully -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. +4. Go to `App Builder` → `Components` → `Micro Frontends & Widgets` to confirm that your bundle appears in the "User" section From 1dfadbc572fab929188b034653dbc9ba846ec03b Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 9 Aug 2022 11:14:46 -0700 Subject: [PATCH 4/7] ENDOC-533 Fix link --- vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md index 900dd8823d..7fc42e75d9 100644 --- a/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md @@ -14,7 +14,7 @@ This tutorial describes how to create a simple Entando Bundle and deploy it into The sections below detail the steps required to generate simple examples of each Entando bundle type. ## Prerequisites -* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` +* Verify dependencies with the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment): `ent check-env develop` * Authenticated Git credentials * An empty Git repository * A running Entando instance From 11eac7d072b9d1d3ad61875b9f8ffbfb2835b124 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 9 Aug 2022 11:17:27 -0700 Subject: [PATCH 5/7] ENDOC-533 exp --- vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md index 900dd8823d..7fc42e75d9 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md @@ -14,7 +14,7 @@ This tutorial describes how to create a simple Entando Bundle and deploy it into The sections below detail the steps required to generate simple examples of each Entando bundle type. ## Prerequisites -* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` +* Verify dependencies with the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment): `ent check-env develop` * Authenticated Git credentials * An empty Git repository * A running Entando instance From 9c528d43b66623800b0a79f173ab9709bd06db0a Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Wed, 10 Aug 2022 17:13:03 -0700 Subject: [PATCH 6/7] ENDOC-533 Remove language from v5 commit --- vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md | 1 - vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md | 1 - 2 files changed, 2 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md index 7fc42e75d9..dfa8115ec8 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md @@ -12,7 +12,6 @@ This tutorial describes how to create a simple Entando Bundle and deploy it into 3. Apply the bundle custom resource to Kubernetes 4. Install the bundle into an application -The sections below detail the steps required to generate simple examples of each Entando bundle type. ## Prerequisites * Verify dependencies with the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment): `ent check-env develop` * Authenticated Git credentials diff --git a/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md index 7fc42e75d9..dfa8115ec8 100644 --- a/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/v7.0/tutorials/create/pb/publish-simple-bundle.md @@ -12,7 +12,6 @@ This tutorial describes how to create a simple Entando Bundle and deploy it into 3. Apply the bundle custom resource to Kubernetes 4. Install the bundle into an application -The sections below detail the steps required to generate simple examples of each Entando bundle type. ## Prerequisites * Verify dependencies with the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment): `ent check-env develop` * Authenticated Git credentials From 181ca1096cce020711623ab7cce90287ffe03894 Mon Sep 17 00:00:00 2001 From: Nathan Shaw Date: Tue, 16 Aug 2022 13:11:07 -0400 Subject: [PATCH 7/7] ENDOC-533 Fix link --- vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md index 31b657bc6b..97bdfd0ecc 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md @@ -14,7 +14,7 @@ This tutorial describes how to create a simple Entando Bundle and deploy it into ## Prerequisites -* Verify dependencies with the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment): `ent check-env develop` +* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` * Authenticated Git credentials * An empty Git repository * A running Entando instance