diff --git a/vuepress/docs/next/docs/curate/bundle-component-details.md b/vuepress/docs/next/docs/curate/bundle-component-details.md index 4857dc959e..e72a06b928 100644 --- a/vuepress/docs/next/docs/curate/bundle-component-details.md +++ b/vuepress/docs/next/docs/curate/bundle-component-details.md @@ -5,15 +5,15 @@ sidebarDepth: 2 # Bundle Component Descriptors -Elements such as pages, content, simple widgets, fragments, and static resources are classified as platform components on Entando. This page describes each of these elements with an example. +Elements such as pages, content, simple widgets, fragments, and static resources that belong to a bundle are classified as platform components on Entando. The following paragraphs describe each of these types and how they can be used in a bundle, with an example. Currently, Entando supports the following component types: ![component-types.png](./img/component-types.png) -Each component is defined by a descriptor YAML located in the bundle `platform` directory, inside the corresponding type as listed below. During the bundle pack phase, the descriptors are added to build the Docker images for the bundle. +Each is defined by a descriptor YAML placed in the corresponding folder inside the bundle `platform` directory. During the pack phase of building an Entando bundle, the descriptors are included in the resulting Docker image following this pattern. -Here is an example structure of a bundle project: +Here is an example structure of the `platform` directory in an Entando Bundle project: ``` bundle-project/ @@ -39,7 +39,7 @@ bundle-project/ ... entando.json <= Bundle project descriptor ``` ->Note: Older names `pageModels` and `contentModels` for `pageTemplates` and `contentTemplates`, respectively, are still supported on Entando 7 but may be removed in a future release. +>Note: Older names `pageModels` and `contentModels`, for `pageTemplates` and `contentTemplates` respectively, are still supported on Entando 7 but may be phased out in future releases. ## Assets The CMS asset descriptor contains the metadata required for uploading and updating bundle assets. @@ -69,7 +69,9 @@ This descriptor contains a list of categories. ## Contents This descriptor enables content to be created and published via a bundle, according to the `status` property. The content ID is optional and enables linking from other components, like content widgets. It can be auto-generated or explicitly declared. -Groups in a content descriptor are configured by the owner group `mainGroup` and the join group `groups`. The owner group consists of users who can manage the content within the App Builder, while the join group consists of users who can view the content. +Groups in a content descriptor are configured by the owner group `mainGroup` and the join group, `groups`. The owner group consists of users who can manage the content within the App Builder, while the join group consists of users who can view the content. + +See an example of [how content is created and managed](../../tutorials/compose/content-tutorial.md). **contents-descriptor.yaml** @@ -93,7 +95,9 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and - code: body values: en: | -

For many people, financial concerns are their number one stress point. Here are 6 ways to help reduce your money stress and get motivated to take control of your finances.

+

For many people, financial concerns are their number one stress point. + Here are 6 ways to help reduce your money stress and get motivated + to take control of your finances.

- code: img values: en: @@ -126,11 +130,12 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and correlationCode: '205' name: Entando_Admin_Console_Overview_4.3.3_EN.pdf -**^ Content Links** -* Content descriptors are loaded in alphabetical order during the bundle creation process. If content X references content Y, content Y must already exist in the bundle for the reference to work. To guarantee referential integrity in a bundle, we recommend that the descriptor name for Y appears earlier in the alphabetical order then content X. -* Contents in bundles cannot make circular references to another content through the link attribute. A circular link is when content A links to content B and B links back to A. Due to the descriptor's alphabetical order of installation, the circular link will cause an error but the links can be added manually after the installation of the bundle. +**^ Code: Links** +* Content descriptors are loaded in alphabetical order during the bundle creation process. If content X references content Y, content Y must already exist in the bundle for the reference to work. To guarantee referential integrity in a bundle, we recommend that the descriptor name for Y appear earlier in the alphabetical order then content X. +* Content in bundles cannot make circular references to each other through the link attribute. A circular link is when content A links to content B and B links back to A. Due to the descriptor's alphabetical order of installation, the circular link will cause an error, but the links can be added manually after the installation of the bundle. ## Content Templates +For some additional details, see the [Content Templates Tutorial](../../tutorials/compose/content-templates-tutorial.md). **contentTemplates-descriptor.yaml** @@ -138,10 +143,12 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and contentType: CNG description: Demo Content Template - # Optional. Define the content template shape in a separate file or inside the descriptor file with `contentShape` + # Optional. Define the content template shape in a separate file or inside + # the descriptor file with `contentShape` contentShapePath: - # Optional. Define the content template shape as shown below or in a separate file with `contentShapePath` + # Optional. Define the content template shape as shown below or in a separate file + # with `contentShapePath` contentShape: >-

$content.Title.text

@@ -179,7 +186,7 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and pos: 13 ## Content Types -For more details on content type properties, refer to the [Content Type documentation](../../tutorials/compose/content-types-tutorial.md). +For some more details, refer to the [Content Types Tutorial](../../tutorials/compose/content-types-tutorial.md). **contentTypes.yaml** @@ -233,6 +240,7 @@ For more details on content type properties, refer to the [Content Type document ognlExpression: string ## Fragments +See an example of [how to use a fragment](../../tutorials/compose/widgets-fragments.md#create-a-new-fragment). **fragments-descriptor.yaml** @@ -277,7 +285,9 @@ This descriptor contains a list of languages to enable during the installation p ## Pages This descriptor creates a page for a bundle. The page layout can be fully configured with a configuration widget. Page status can be `published` or `draft`. -Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The `ownerGroup` property specifies the group of users who can manage the entity in the App Builder. The `joinGroups` property specifies those who can view or access the page. For example, setting `ownerGroup` to "free" means anyone with access to the App Builder can manage the page, whereas setting `joinGroup` to "free" means any end user can view the page in the application. +Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The `ownerGroup` property specifies the group of users who can manage the page in the App Builder. The `joinGroups` property specifies those who can view or access the page. For example, setting `ownerGroup` to "free" means anyone with access to the App Builder can manage the page, whereas setting `joinGroup` to "free" means any end user can view the page in the application. + +See an example of [how a page is created and managed](../../tutorials/compose/page-management.md) in the App Builder. **pages-descriptor.yaml** @@ -325,6 +335,7 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The pos: 13 ## Page Templates +Here's some more details about [how page templates work on Entando](../../tutorials/compose/page-management.md#create-a-page-template). **pageTemplate-descriptor.yaml** @@ -346,14 +357,16 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The x2: 11 y2: 1 defaultWidget: - code: my-widget # The widget code to apply when using the button "apply default widgets" in the page configuration UI + code: my-widget # The widget code to apply when using the button + # "apply default widgets" in the page configuration UI # A simplified way to define frames - pos: 1 description: Breadcrumb sketch: { x1: 0, y1: 0, x2: 11, y2: 1 } - # Optional. Define the page template in a separate file or inside the descriptor file with `template` + # Optional. Define the page template in a separate file or inside the descriptor file + # with `template` templatePath: page.ftl # Optional. Define the page template as below or in a separate file with `templatePath` @@ -375,7 +388,9 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The ## Static Resources -The `resources` folder in the `platform` directory contains all static resources. These files will be uploaded to Entando using the same structure, found in the App Builder File Browser public folder. +The `resources` folder in the `platform` directory contains all static resources. Once the bundle is installed, they can be found inside the App Builder File Browser, with the same file structure. + +See which [digital formats are supported on Entando](../../tutorials/compose/digital-assets-tutorial.md). ``` platform/ ... @@ -399,9 +414,9 @@ To use static files in a Widget or Page Template, use the FTL tag `<@wp.resource ``` ent ecr get-bundle-id repo=url ``` -It should return an 8 digit string of numbers and letters, e.g. bundle-id=8785d979. +It should return an 8 digit string of numbers and letters, e.g. BUNDLE-ID=8785d979. -2. YOUR-BUNDLE-CODE is YOUR-BUNDLE-NAME-YOUR-BUNDLE-ID: +2. YOUR-BUNDLE-CODE is YOUR-BUNDLE-NAME appended with YOUR-BUNDLE-ID: If YOUR-BUNDLE-NAME=first-bundle and YOUR-BUNDLE-ID=8785d979, then YOUR-BUNDLE-CODE=first-bundle-8785d979 @@ -435,9 +450,11 @@ Here are example tags to access static resources in a typical bundle: # Optional. The configUI configUi: - customElement: my-widget-config # The name of the custom element used to render the configUi + customElement: my-widget-config # The name of the custom element used to render + # the configUi resources: - - /static/js/main.js # The resources necessary for the custom element to render the configUI, like the code + - /static/js/main.js # The resources necessary for the custom element to + # render the configUi, i.e., the code **Note**: To configure micro frontends to access static assets, Entando provides a path with the following snippet: ``` js diff --git a/vuepress/docs/next/docs/curate/bundle-details.md b/vuepress/docs/next/docs/curate/bundle-details.md index a63433a0fb..986f5fa3fc 100644 --- a/vuepress/docs/next/docs/curate/bundle-details.md +++ b/vuepress/docs/next/docs/curate/bundle-details.md @@ -2,18 +2,18 @@ sidebarDepth: 2 --- -# Entando Bundle +# The Entando Bundle -The structure of an Entando Bundle leverages composable development methods, decoupling microservices, micro frontends, API management, and services such as databases. The **ent bundle CLI** module administers the process, using the descriptor `entando.json`. This single bundle descriptor defines all the components and resources of the docker-based bundle. The following page describes the descriptor, the structure, its conventions, and the building process. +The Entando Bundle is the smallest building block from which applications are built on Entando. It leverages composable development methods, decoupling microservices, micro frontends, and APIs to make it modular and easier to containerize. The **ent bundle CLI** administers the process, using a single descriptor `entando.json` to define the docker-based bundle. This page describes the Entando Bundle structure, the descriptor file, its conventions, and the packaging process. The docker-based approach is an improvement on the previous Entando Bundle structure and to see the differences, refer to the [Bundle Evolution](../reference/bundle-comparison.md) page. ## Entando Bundle Conventions * There is a single bundle descriptor, `entando.json`, initialized and managed by the [ent bundle CLI](../getting-started/ent-bundle.md). -* Microservices and micro frontends can be built independently, each with their own folders. -* The `platform` directory is dedicated to platform specific components such as fragments, pages, and static resources. For more information on component types and descriptors, see the [Bundle Component Details](bundle-component-details.md) page. -* The `svc` directory is allocated for auxiliary services and the docker-compose configuration files that define them. The ent bundle module enables, starts and stops the services. MySQL, PostgreSQL, and Keycloak services are available with Entando out of the box, and for more details, go to the [ent CLI Services page](../getting-started/ent-svc.md). +* Microservices (MSs) and micro frontends (MFEs) are built and processed independently, with a Docker image for the bundle and for each MS. +* The `platform` directory is dedicated to project specific components such as fragments, pages, and static resources. For more information on component types and corresponding descriptors, see the [Bundle Component Details](bundle-component-details.md) page. +* The `svc` directory is allocated for auxiliary services and the docker-compose configuration files that define them. The ent bundle commands enable, start and stop the services. MySQL, PostgreSQL, and Keycloak services are available with Entando out of the box, and for details on adding custom services, go to the [ent Bundle CLI Services page](../getting-started/ent-svc.md). * Optionally, a thumbnail for your bundle can be set by adding a JPG or PNG image file to the bundle root folder. The file must be named "thumbnail" and be 100kb or less, e.g. thumbnail.png. ## Project Structure @@ -53,9 +53,9 @@ platform/ <= platform specific components ![Bundle Development Process](./img/development-process.jpg) -The ent bundle CLI module manages the building and publishing of an Entando Bundle. From initialization to installation, from adding MFEs and MSs to calling for services such as Keycloak and making API claims, the ent bundle commands streamline the development process. +The ent bundle CLI module manages the building and publishing of an Entando Bundle. From initialization to installation, from adding MFEs and MSs to calling for services and making API claims, the ent bundle commands streamline the development process. -At initialization, the project scaffolding is built. A project can be started from scratch with this structure or retrieved interactively from an Entando Hub as a starting point for new bundles. Microservices, micro frontends, components, services, and API claims can then be added. At this stage, components can be run locally and independently with the ent bundle commands. +At initialization, the project scaffolding is built. A project can be started from scratch with this structure or downloaded interactively from an Entando Hub with the `ent bundle init --from-hub` command. Microservices, micro frontends, components, services, and API claims can then be added, manually or with the ent bundle CLI. At this stage, components can be run locally and independently. The next steps build and pack the project using the bundle descriptor. The specifics depend on the component type and stack. The build phase constructs the microservices and micro frontends while the pack command generates the artifacts and Docker images. Images are built for the bundle and for each microservice. @@ -63,9 +63,9 @@ In the publish step, images are pushed to a Docker registry and tagged according ![Bundle Publishing Process](./img/publishing-process.jpg) -Finally, the bundle is deployed into the Local Hub of a running Entando instance where it can then be installed. Any improvements to the bundle can be made by repeating the **four steps: pack, publish, deploy and install**. Alternatively, the install step can be done in the App Builder UI by the composer designing the application. +Finally, the bundle is deployed into the Local Hub of a running Entando instance where it can be installed. Any improvements to the bundle can be made by repeating the **four steps: pack, publish, deploy and install**. Alternatively, the install step can be completed in the App Builder UI when composing an application by upgrading the version. -At every phase of the process, options are available to fine-tune the process, and to see more information, go to the [ent bundle CLI](../getting-started/ent-bundle.md) documentation. +At every phase of the process, options are available to fine-tune the process, and for more specifics, see the [ent bundle CLI](../getting-started/ent-bundle.md) documentation. ## Bundle Descriptor entando.json The following is a list of specifications for the bundle descriptor and its component parts. @@ -73,13 +73,13 @@ The following is a list of specifications for the bundle descriptor and its comp ### Bundle Descriptor Specifications |Name|Type|Required|Description| |:---|:---|:-|:-----------------------| -|`description`|String| No |A description of the bundle project shown in the App Builder| +|`description`|String| No |A description of the bundle project displayed in the App Builder| |`displayName`|String|No|A descriptive label used in the UI in place of a name| |`global`|[Global[]](#global-specification)|No|Global bundle configuration items| |`microfrontends`|[Micro Frontends](#micro-frontends-specifications)|No|Bundle micro frontends| |`microservices`|[Microservices](#microservices-specifications)|No|Bundle microservices| |`name^`|String|Yes|The bundle project name used as the default Docker image name| -|`version`|String|Yes|The bundle version used as the default Docker image tag| +|`version`|String|Yes|The bundle version used in the default Docker image tag| ^ Bundle Name: A bundle name may only contain lowercase letters, numbers, periods(.), and dashes(-). They cannot start or end with periods or dashes. ```json @@ -111,7 +111,7 @@ The following is a list of specifications for the bundle descriptor and its comp |`stack`|Enum|Yes|*spring-boot
*node
*custom|Microservice stack | |`version`|String|Required only for a custom stack||Microservice version override| -**^ dbms none**: Oracle and other DBMS types are not supported for automatic deployment in a container. Bundle env variables should be used instead, similar to connecting the EntandoApp to an [external database](../../tutorials/devops/external-db.md). +**^ dbms none**: Oracle and other DBMS types are not supported for automatic deployment in a container. Bundle env variables should be used instead, similar to this instance of an [external database](../../tutorials/devops/external-db.md). #### Microservices Sample Code ```json @@ -147,7 +147,7 @@ The following is a list of specifications for the bundle descriptor and its comp - To utilize **environment variables**, inline or based on Kubernetes Secrets, see the [Plugin Environment Variables](../../tutorials/devops/plugin-environment-variables.md) tutorial. - - Entando uses the `healthCheckPath` to monitor the health of the microservice. A plugin in an Entando Bundle can use any technology, as long as it provides a health check service configured via the `healthCheckPath`. This path must be specified in the descriptor file and return an HTTP 200 or success status. This can be implemented by a Java service included with the Entando Blueprint in the Spring Boot application. You can also [use a Node.js service as shown here](https://github.com/entando-samples/ent-project-template-node-ms/blob/main/src/main/node/controller/health-controller.js). + - Entando uses the `healthCheckPath` to monitor the health of the microservice. A plugin or microservice in an Entando Bundle can use any technology, as long as it provides a health check service configured via the `healthCheckPath`. This path must be specified in the descriptor file and return an HTTP 200 or success status. This can be implemented by a Java service included with the Entando Blueprint in the Spring Boot application. You can also [use a Node.js service as shown here](https://github.com/entando-samples/ent-project-template-node-ms/blob/main/src/main/node/controller/health-controller.js). ### Micro Frontends Specifications |Name|Type|Required|Possible Values|Description| @@ -160,18 +160,18 @@ The following is a list of specifications for the bundle descriptor and its comp |`contextParams`|String[]| Yes | | Information extracted from the application context | |`group`|String|Yes||Visibility group name| |`name`|String|Yes||Micro frontend name| -|`stack`|Enum|Yes|*react
*angular
*custom|MFE stack| -|`type`|Enum|Yes|*widget *widget-config *app-builder|Type of MFE| |`nav`|[MenuEntry[]](#menuentry-specification)|No||Bundle menu global links| |`params`| [MfeParam[]](#mfeparam-specification) |Yes| | User configuration for executing a widget| |`paths`|String[]|Yes for `type=app-builder` and `slot=content`||App Builder activation paths| |`publicFolder`|String|No|Default is `public`|MFE public folder (typically where index.html is located)| |`slot`|Enum|Yes for `type=app-builder`|*primary-header *primary-menu *content|Named reference to an App Builder embedded position in a specific layout| +|`stack`|Enum|Yes|*react
*angular
*custom|MFE stack| |`titles`|String[]|Yes for `type=widget`||Localized widget labels| +|`type`|Enum|Yes|*widget *widget-config *app-builder|Type of MFE| |`version`|String|Required only for custom stack MFE||Microfrontend version override| #### Configure a Path for Static Assets -To configure your micro frontend with access to static assets, Entando provides two paths, one for widgets and another for EPCs. +To configure your micro frontend with access to static assets, Entando provides two paths, one for widgets and another for [Entando Platform Capabilities (EPCs)](../../tutorials/create/mfe/epc.md). * For widgets: `window.entando?.widgets['YOUR-MFE']?.basePath;` @@ -216,7 +216,7 @@ A custom `category` provides an organizing classification for `Widgets`, to appe ### API Claim Specification |Name|Type|Required|Possible Value|Description| |:-|:-|:-|:-|:------------------------| -|`bundle`|String|Yes only for `type=external`||Bundle Docker URL| +|`bundle`|String|Yes only for `type=external`||Bundle Docker URL| |`name`|String|Yes||Name| |`serviceName`|String|Yes||The name of the microservice| |`serviceUrl`| String| No ||The URL of the microservice deployed in the local environment| @@ -238,25 +238,21 @@ A custom `category` provides an organizing classification for `Widgets`, to appe } ] ``` -For more information, go to the [API Management](../getting-started/ent-api.md) page. +For more information, see the [API Management](../getting-started/ent-api.md) page. ### Command Specification -|Name|Type|Required| Description| -|:-|:-|:-|:------------------------| -|`build`|String|No| Custom build command| -|`pack`|String|No| Custom pack command| -|`run`|String|No| Custom run command| +|Name|Type|Required| Default (Stack dependent) | Description| +|:-|:-|:-|:-|:------------------------| +|`build`|String|No| mvn test, npm run test | Custom build command| +|`pack`|String|No| mvn spring-boot:run, npm run start | Custom pack command| +|`run`|String|No| mvn package, npm run build | Custom run command| -#### Command Spec Sample Code +#### Custom Command Sample Code ```json "commands": { "run": "mvn -Dspring-boot.run.arguments=\"--server.port=8082\" spring-boot:run" } ``` -Depending on the stack type, default values are: -- build: mvn test, npm run test -- run: mvn spring-boot:run, npm run start -- pack: mvn package, npm run build ### EnvironmentVariables Specification |Name|Type|Required|Description| @@ -304,12 +300,12 @@ Depending on the stack type, default values are: The following are platform-provided runtime variables. |Name| Type | Description| |:-|:---|:----------------------------------| -|`ENTANDO_TENANT_CODE`| string | For multitenant environments only, automatically inserted to identify the owner tenant | +|`ENTANDO_TENANT_CODE`| string | For multitenant environments only, automatically inserted to identify the owner tenant. | |`KEYCLOAK_REALM`| string | Keycloak or Red Hat Single Sign-On (RH-SSO) realm to be used by the MS. | |`KEYCLOAK_AUTH_URL` | string | Keycloak/RH-SSO URL to be used by the MS.| |`KEYCLOAK_CLIENT_SECRET`| `secretKeyRef[]`| Keycloak/RH-SSO autogenerated clientSecret to be used by the MS. | | `KEYCLOAK_CLIENT_ID`| `secretKeyRef[]`| Keycloak/RH-SSO autogenerated clientId to be used by the MS. | -|`SERVER_SERVLET_CONTEXT_PATH` | string | Context path used to access the MS. Automatically handled by a Spring Boot MS, but can be manually set for other `stack` types.| +|`SERVER_SERVLET_CONTEXT_PATH` | string | Context path used to access the MS. Automatically handled by a Spring Boot MS but can be manually set for other `stack` types.| | `SPRING_PROFILES_ACTIVE`| string | Application profile to use when the MS runs on Entando, differentiating dev vs prod at runtime. Automatically handled by a Spring Boot MS but can be manually managed if using another technology `stack`. | | `SPRING_DATASOURCE_URL`| string| Provisioned database JDBC connection URL. Automatically handled by a Spring Boot MS but can be manually managed if using another technology `stack`. | | `SPRING_DATASOURCE_USERNAME` | string| Provisioned database username. Automatically handled for a Spring Boot MS, but can be manually managed if using another technology `stack`.| diff --git a/vuepress/docs/next/docs/curate/bundle-filters.md b/vuepress/docs/next/docs/curate/bundle-filters.md index c49a7f808b..1f0b75cc18 100644 --- a/vuepress/docs/next/docs/curate/bundle-filters.md +++ b/vuepress/docs/next/docs/curate/bundle-filters.md @@ -1,12 +1,15 @@ +--- +sidebarDepth: 2 +--- # Filtering Bundles -Entando Bundles are filterable by component, status or textual search from the App Builder user interface. +Entando Bundles can be filtered by its status, component part, or textual search from the App Builder user interface. ![App Builder bundle filtering](./img/bundle-filtering.png) ## Filtering Bundles by Component -To filter a bundle by component, its custom resource on the Entando Cluster must contain appropriate labels. Valid labels are: widget, plugin, fragment, pageTemplate, contentType and contentTemplate. To correctly define a label in a K8s resource requires both a key and value, but Entando uses only the key when filtering. Although the value is arbitrary, we recommend a setting of `"true"` for clarity and simplicity. +To filter a bundle by component, its custom resource in the Entando Cluster must contain appropriate labels. Valid labels are: widget, plugin, fragment, pageTemplate, contentType and contentTemplate. To correctly define a label in a K8s resource requires both a key and value, but Entando uses only the key when filtering. Although the value is arbitrary, we recommend a setting of `"true"` for clarity and simplicity. ### Supported Labels Keys @@ -68,13 +71,13 @@ spec: ## Filtering Bundles by Status -Entando Bundles are filterable by availability and install status. Select the `Explore` tab to see the full list of bundles available in the Kubernetes cluster. Select the `Installed` tab to see the list of currently installed bundles. +Entando Bundles are filterable by availability and install status. Select the `Explore` tab to see the full list of bundles available in the Kubernetes cluster. Select the `Installed` tab to see the list of currently installed bundles in the Local Hub of the App Builder. ## Filtering Bundles by Textual Search -Use the textual search to return bundles that contain certain keywords in their name, description or version. When creating a new bundle, bear in mind that a textual search is performed against data extracted from the bundle CRD file. +Use the textual search to return bundles that contain certain keywords in their name, description or version. When creating a new bundle, bear in mind that a textual search is performed against data extracted from the bundle custom resource definition. ## Mixing Search Criteria -Filtering can be refined by combining component, status and textual search criteria. For example, you could search for all available bundles (filter by status) that contain `Page Templates` (filter by component) and the word `Login` in their name (filter by textual search). +Filtering can be refined by combining component, status and textual search criterias. For example, you could search for all available bundles (filter by status), that contain `Page Templates` (filter by component), with the word `Login` in the name (filter by textual search). diff --git a/vuepress/docs/next/docs/curate/bundle-presentation-config.md b/vuepress/docs/next/docs/curate/bundle-presentation-config.md index d41be3070b..db6b2df82c 100644 --- a/vuepress/docs/next/docs/curate/bundle-presentation-config.md +++ b/vuepress/docs/next/docs/curate/bundle-presentation-config.md @@ -1,11 +1,16 @@ +--- +sidebarDepth: 2 +--- # Customize Bundle Info Shown in App Builder -An example of how bundles are displayed in the Local Hub of the App Builder is shown below: +To modify what is displayed for your bundles in the Local Hub, there are a few specifications that can be customized. This is helpful when there are many bundles or they are shared across teams and organizations. + +Bundles are typically displayed in the Local Hub of the App Builder like this: ![Hub user interface in Entando App Builder](./img/local-hub-page.png) -The corresponding custom resource file on Kubernetes contains content similar to the following: +The corresponding Kubernetes custom resource file looks similar to this: ``` apiVersion: entando.org/v1 @@ -32,10 +37,10 @@ spec: version: 0.0.1 ``` -Spec Definitions: +These are the specifications that can be customized: | Field | UI Element | -|---------------------------------|---------------------------------------------------------------------------| -| `spec.details.name` | Set the bundle title | -| `spec.details.description` | Set the bundle description (only visible in list format) | -| `spec.details.dist-tags.latest` | Set the latest version of the bundle | \ No newline at end of file +|-------------------------|---------------------------------------------------------------------------| +| `spec.details.name` | The bundle title | +| `spec.details.description` | The bundle description (only visible in list format) | +| `spec.details.dist-tags.latest` | The latest version of the bundle | \ No newline at end of file diff --git a/vuepress/docs/next/docs/curate/bundle-versions-faq.md b/vuepress/docs/next/docs/curate/bundle-versions-faq.md index 0d2596292e..aac51221a5 100644 --- a/vuepress/docs/next/docs/curate/bundle-versions-faq.md +++ b/vuepress/docs/next/docs/curate/bundle-versions-faq.md @@ -2,23 +2,22 @@ sidebarDepth: 1 --- -# Bundle Versions and Updates - FAQ +# Bundle Versions - FAQ ## Support ### 1. Does the Entando Platform support bundle versioning? -A bundle is an independent package containing one or more components. -As in other packaging systems, the [Entando Component Registry](../compose/local-hub-overview.md)(ECR) supports bundle versioning, allowing developers to create and release updates of their package over time. +A bundle is a self-contained package containing one or more components such as microservices and micro frontends. As in other packaging systems, the [Entando Component Registry](../compose/local-hub-overview.md) (ECR) supports bundle versioning, allowing developers to create and release updates of their package over time. ## How-Tos ### 1. How do I create a new version of a bundle? -To release new versions of your bundle after changes have been made, edit the `entando.json` with the new version number for the bundle, then pack and publish your images to Docker. Docker will provide tags to update the bundle version. Once you deploy and install the bundle, the new version number will appear in the App Builder. +To release new versions of your bundle after changes have been made, edit the `entando.json` with the new version number, then pack and publish your images to Docker. Docker will provide tags to update the bundle version. Once you deploy and install the bundle, the new version number will appear in the App Builder. Micro frontends and microservices can have their own version numbers, independent of the bundle version, and can be updated in the same way. ### 2. My bundle contains a microservice generated with the Entando Component Generator; does the version of the microservice have to be the same as the bundle version? -The version of the microservice - or the Docker image associated with the microservice - isn't bound to the version of the bundle containing the microservice itself. +The version of the microservice - or the Docker image associated with the microservice - isn't bound to the version number of the bundle it is a part of. Thus, the same microservice can be used in different bundles. This gives the developer control over the bundle release process, especially in situations where the bundle may contain many components. @@ -27,7 +26,7 @@ This gives the developer control over the bundle release process, especially in ### 1. How is a bundle version defined? -Bundle versions are defined by the creator and set in the bundle descriptor `entando.json`. You can have multiple versions of a bundle as long as they are defined and tagged as such. +Bundle versions are defined by the creator and set in the `entando.json` bundle descriptor. You can have multiple versions of a bundle as long as they are defined and tagged as such. ```json { @@ -49,9 +48,9 @@ Follow the recommended [semantic versioning 2.0.0](https://semver.org/#semantic- ### 3. Can I publish all versions of any bundle to my Local Hub for development? -To make all versions for all bundles available in the Local Hub, edit the environment variable `ENTANDO_BUNDLE_TAGS_TYPES` in the component manager (CM) deployment to have the value, `dev,prod`. Tag types can also be set to `dev` or `prod`. +To make all versions for all bundles available in the Local Hub, edit the environment variable `ENTANDO_BUNDLE_TAGS_TYPES` of the Entando Component Manager (ECM) deployment to have the value, `dev,prod`. Tag types can also be set to only `dev` or `prod`. -For individual bundles, see the [Bundle Management page](../getting-started/ent-bundle.md#generate-cr) for details about how to utilize the ent CLI's bundle commands to select development, production, or both types of bundles. +For individual bundles, see the [Bundle Management page](../getting-started/ent-bundle.md#generate-cr) for details about how to utilize the ent CLI's bundle commands to select for development, production, or both types of bundles. diff --git a/vuepress/docs/next/docs/curate/hub-details.md b/vuepress/docs/next/docs/curate/hub-details.md index 2a8c231f6f..b46e805043 100644 --- a/vuepress/docs/next/docs/curate/hub-details.md +++ b/vuepress/docs/next/docs/curate/hub-details.md @@ -4,54 +4,54 @@ sidebarDepth: 2 # Entando Hub Features and Definitions ## Overview -The Entando Hub is the central catalog where components are published, organized and shared. The reusable components called Bundle Groups come with versioning and publishing management capabilites in the Hub UI. The following describes the details of how this process is defined and accomplished. +The Entando Hub is the central catalog where components are published, organized and shared. When building composable applications, building blocks called bundles or bundle groups are chosen from this catalog and placed onto a page. The Hub UI provides publishing and versioning capabilites for these reusable components and the following describes the details of how this process works. -Entando Hub Features: +**Entando Hub Features:** -- Centralize components and business capabilities for use across teams, groups, or clients +- Centralize components and packaged business capabilities (PBCs) for use across teams, projects, or clients - Publish and manage components, and communicate component features, versions and metadata -- Perform business-level assessment of component readiness +- Perform business-level assessments of component readiness -The Hub can be utilized in several ways in any Entando Application: -* The **Local Hub**, included in the Entando App Builder, displays a collection of ready-to-use components. They can be used to compose an application or as a starting point to create new components. +The Entando Platform provides three variations of the catalog. They are all directly accessible from the App Builder to make it easy to find and select the components to build your applications. -* **Entando Cloud Hub** is the public catalog containing packaged business capabilities and components provided by Entando and its partners throughout the world. +* The **Local Hub**, included in the Entando App Builder, displays a collection of ready-to-use components. They can be used to compose an application or as a starting point to create your own. -* **Enterprise Entando Hub**, applied and curated by Entando clients and partners, it can be used to share components within their respective organizations or made available for public use. +* **Entando Marketplace** is the public catalog presenting the packaged business capabilities and components developed by Entando and its partners throughout the world. -[Installation and User Guide](../../tutorials/solution/entando-hub.md) +* The **Enterprise Entando Hub** can be added to your Entando instance for your organization to share components, privately within teams, with clients, or with the public. + +The remainder of this document explores the parameters of the Enterprise Hub, and to see how it is installed, here is the [Installation and User Guide](../../tutorials/solution/entando-hub.md). ## Bundle Group Definitions -The key entities in an enterprise Hub are: +The key entities in a Hub are as follows: -- `Bundle Group`: A Bundle Group is a Hub entry, a single unit containing one or more Entando Bundles. -- `Bundle`: An Entando Bundle is the deployment unit within an Entando Application. A bundle can contain one or more components such as micro frontends, microservices, or any of the [component types](../../docs/curate/bundle-component-details.md) allowed in Entando. -- `Bundle Group Version`: A Bundle Group can have one or more versions, each with a particular status. -- `Category`: Each Bundle Group belongs to a specific category. The default categories are solution template, packaged business capability (PBC), and component collection. An admin of an enterprise Hub can create and refine the categories as desired. -- `Organization`: Bundle Groups belong to a single organization. Authors and managers can only update entries within their own organization. A single instance of the Hub can have multiple organizations. +- `Bundle`: An Entando Bundle is the basic deployment unit within an Entando Application. A bundle can contain one or more component such as micro frontends, microservices, or any of the [component types](../../docs/curate/bundle-component-details.md) allowed on Entando. +- `Bundle Group`: A bundle group is a Hub entry, a single unit containing one or more Entando Bundle. +- `Bundle Group Version`: A bundle group can have one or more versions, each with a particular status. +- `Category`: Each bundle group belongs to a specific category. The default categories are solution template, packaged business capability (PBC), and component collection. Additional categories can be customized for any Enterprise Hub. +- `Organization`: Bundle groups belong to a single organization. Authors and managers can only update entries within their own organization. A single instance of the Hub can have multiple organizations. - `User`: User identity is managed within Keycloak, where users are granted roles within a Hub instance. Users must be created in Keycloak, then added in the Hub and assigned to a specific organization. - -> A private repository can be used for a bundle, but this requires [an additional Kubernetes Secret](../../tutorials/curate/private-git-repo.md) before deployment via the App Builder. +> A private repository can be the source of a bundle, but this requires [an additional Kubernetes Secret](../../tutorials/curate/private-git-repo.md) before deployment in the App Builder. ## Roles -Three roles are defined to provide access to the enterprise Hub features: +Three roles are available for the Enterprise Hub UI to manage its catalog. All roles are tied to an organization and are defined as follows: -- `eh-author`: An author can create and edit Bundle Groups for their organization and submit them for publication. They can generate an API key. -- `eh-manager`: A manager has the capabilities of an author, but can also approve a publication request for their organization. -- `eh-admin`: An admin has full access to create, update, and delete Bundle Groups and manage users for the entire Hub instance. An admin can also create categories, organizations and private catalogs, assign users to organizations, and generate API keys. -- `guest`: Any user without one of the preceding roles is considered a guest in the enterprise Hub and is given a read-only view of the public catalog. This is also true for unauthenticated users. +- `eh-author`: An author can create and edit bundle groups and submit them for publication. They can also generate an API key for private Hubs. +- `eh-manager`: A manager has all the capabilities of an author, but also has the job of approving bundle groups for publication. +- `eh-admin`: An admin has full access to create, update, approve, and delete bundle groups, and manage users for the entire Hub instance. An admin can create categories, organizations and private catalogs, assign users to organizations, and generate API keys for private catalogs. +- `guest`: Any user without one of the preceding roles is considered a guest in the Enterprise Hub and is given a read-only view of a public catalog. This is also true for unauthenticated users. To assign roles to a new Hub user, see the [Entando Hub Installation and User Guide](../../tutorials/solution/entando-hub.md#user-management) ## Bundle Group Versions -The list of Bundle Group versions can be seen by clicking `View Versions` for any entry in the catalog: +Available bundle group versions can be viewed or edited from the kebab-dropdown menu of an entry as seen here: ![hub-actions.png](./img/hub-actions.png) -The following rules apply to Bundle Group versions: +The following versioning rules apply to bundle groups: - Once the first version of a group is published, the organization, name, and category can no longer be changed. -- A new version of a Bundle Group can be created (via the `New Version` option) after the first version has been published. +- A new version of a bundle group can be created only after the first version has been published. - There can be at most two active versions: one draft or publication requested version, and one published version. - When a new version is published, the previous version is set to `Archived`. - Archived versions are only visible in the versions view and are not shown elsewhere in the user interface. @@ -60,24 +60,24 @@ The following rules apply to Bundle Group versions: ## Bundle Group Status -The possible statuses for each version of a Bundle Group are as follows: +The possible statuses for each version of a bundle group are as follows: -- `Draft`: This is the default status for the first version of a Bundle Group. -- `Publication Request`: An `eh-author` sets a version to this status to request the `eh-manager` or `eh-admin` to review the version and approve it for publication. The manager or admin may also edit versions with this status. -- `Published`: Versions with this status are visible in the home page catalog of available Bundle Groups, and are also available in the App Builder-facing API. An `eh-manager` or `eh-admin` may edit published versions. +- `Draft`: This is the default status for a newly created bundle group. +- `Publication Request`: An `eh-author` sets a version to this status to request the `eh-manager` or `eh-admin` to review and approve it for publication. The manager or admin may edit versions with this status. +- `Published`: Versions with this status are visible in the Hub's catalog of available bundle groups, and are also available in the App Builder-facing API. An `eh-manager` or `eh-admin` may edit published versions. - `Archived`: Previously published versions are assigned this status. No edits can be made to an archived version. -- `Deletion Request`: An `eh-manager` or `eh-admin` can delete versions once this status has been set. +- `Deletion Request`: An `eh-manager` or `eh-admin` can delete versions once a group has been assigned this status. Notes: - An `eh-author` can change any field except organization while a version is in `Draft` status. -- There is no automated notification process when a publication request is made for a Bundle Group version. +- There is no automated notification process when a publication request is made for a bundle group version. -## Application Details +## Entando Hub Application Details -An Entando Hub includes the following key components: +An Enterprise Entando Hub includes the following key components: #### Micro Frontends / Widgets -- `Entando Hub App`: This is the main micro frontend which contains the management UI for the Hub entities noted above. +- `Entando Hub App`: This is the main micro frontend which contains the management UI for the catalog noted above. - `Entando Hub Login`: This is an optional login component which can be used in a page’s top navigation. #### Microservices diff --git a/vuepress/docs/next/docs/curate/img/publishing-process.jpg b/vuepress/docs/next/docs/curate/img/publishing-process.jpg index 971adc1d50..e19e3b37fd 100644 Binary files a/vuepress/docs/next/docs/curate/img/publishing-process.jpg and b/vuepress/docs/next/docs/curate/img/publishing-process.jpg differ diff --git a/vuepress/docs/next/docs/curate/troubleshooting-guide.md b/vuepress/docs/next/docs/curate/troubleshooting-guide.md index 4a701ae078..0f85003d9f 100644 --- a/vuepress/docs/next/docs/curate/troubleshooting-guide.md +++ b/vuepress/docs/next/docs/curate/troubleshooting-guide.md @@ -1,30 +1,33 @@ -# Troubleshooting ECR +--- +sidebarDepth: 2 +--- +# Troubleshooting the Entando Local Hub -## How do I access the logs? +## 1. How do I access the logs? **A bundle installation or removal has failed. How do I access the logs?** -The Entando Component Manager (CM) logs can be viewed using CLI tools like kubectl or oc, or visualization dashboards like OpenShift or K9s. +The Entando Component Manager (ECM) logs can be viewed using CLI tools like kubectl or oc, or visualization dashboards like OpenShift or K9s. ### Solution -1. To view the Component Manager logs, find the CM pod name in your instance: +1. To view the Component Manager logs, find the ECM pod name in your instance: ``` ent kubectl get pods ``` -It will be something like this: `quickstart-cm-deployment-7f74757f97-xnlbn` +It should be something like this: `quickstart-cm-deployment-7f74757f97-xnlbn` -2. Using your CM pod name and namespace, use this command to view the logs: +2. Using the ECM pod name and your namespace, use this command to view the logs: ``` -ent kubectl logs -f YOUR-PODNAME-7f74757f97-xnlbn -n YOUR-NAMESPACE +ent kubectl logs -f YOUR-ECM-PODNAME -n YOUR-NAMESPACE ``` >Notes: >1. Use the [ent CLI](../getting-started/entando-cli.md) to send commands directly to Kubernetes from the host machine. >2. The `-f` flag is optional and used to follow the logs for debugging purposes. The namespace (-n) is also optional if ent has a profile configured. -## ERROR - File not found in bundle +## 2. ERROR - File not found in bundle **Installation fails because a file has not been found in the bundle** -When a component referenced in the entando.json is missing or not properly called, the bundle installation fails and the error is reported in the logs. +When a component referenced in the `entando.json` is missing or not properly called, the bundle installation fails and the error is reported in the logs. ``` ERROR - File with name {filename} not found in the bundle @@ -34,19 +37,19 @@ ERROR - File with name {filename} not found in the bundle Verify that the component named in the descriptor file is actually at the specified location and the reference is properly formatted. Then, publish the updated bundle with `ent bundle publish`. -## My plugin Docker image is unreachable +## 3. My microservice's Docker image is unreachable **Bundle installation fails due to plugin images that are not reachable** -A bundle installation does not complete successfully because a plugin in a bundle, defined by a Docker image, is not available. +A bundle installation does not complete successfully because a microservice in a bundle, defined by a Docker image, is not available. ### Solution -This may happen if the Docker image for the plugin is located in a private registry or not yet published. Verify that the Docker image you are referencing is published, correctly formatted, and publicly available. Then, publish the updated bundle with `ent bundle publish`. +This may happen if the Docker image for the microservice is located in a private registry or not yet published. Verify that the Docker image you are referencing is published, correctly formatted, and publicly available. -## How do I uninstall a bundle +## 4. How do I uninstall a bundle **I can't uninstall a bundle because some components are in use** -When uninstalling an installed bundle, the Entando Component Manager verfies that the bundle components are not in use by any other component. An error message informs you and does not allow the removal. +When uninstalling a previously installed bundle, the Entando Component Manager verifies that the bundle components are not in use elsewhere. If any part of the bundle is in use, an error message informs you and does not allow the removal. ### Solution -A bundle cannot be uninstalled if any of its components are in use. To uninstall the bundle, the user must manually remove all references to it and all its component. \ No newline at end of file +A bundle cannot be uninstalled if any of its components are in use. To uninstall the bundle, the user must manually remove all references to it and its component parts. \ No newline at end of file diff --git a/vuepress/docs/next/docs/curate/uninstall-flow.md b/vuepress/docs/next/docs/curate/uninstall-flow.md index b0a4fdbe22..1380c6b078 100644 --- a/vuepress/docs/next/docs/curate/uninstall-flow.md +++ b/vuepress/docs/next/docs/curate/uninstall-flow.md @@ -1,26 +1,31 @@ +--- +sidebarDepth: 2 +--- # Bundle Upgrade, Downgrade, and Uninstall -An application bundle that has been installed in the Entando App Builder can be upgraded to a new version, reverted to a previous version or uninstalled at any time. You can update the bundle or just a component within that bundle, all within the App Builder. +An application bundle that has been installed in the Entando App Builder can be removed, upgraded to a new version, or downgraded to a previous version at any time. You can update the bundle group or just a component within that bundle. ## Upgrade or Downgrade Bundle Version -1. Log in to your App Builder instance and select `Hub` from the navigation on the left to enter your Local Hub. +1. Log in to your App Builder instance and select `Hub` from the left navigation bar to go to your Local Hub. 2. Click the `Installed` button to open a pop-up window with the options to update or uninstall the bundle. -3. Click the `Update` button to see a list of versions available. Choose a version. A warning will appear regarding the possible loss of features or data with the update. You may wish to review the bundle's release notes before confirming the upgrade or rollback. +3. Click the `Update` button to see the list of available versions. Choose one and a warning will appear regarding the possible loss of features or data with the update. You may wish to review the bundle's release notes before confirming the upgrade or rollback. 4. Once you confirm, a page listing all the components in the bundle appears. You can `Update All` or select each component to be updated or skipped. 5. Click `Ok` to finish. ## Uninstall a Bundle -1. Log in to your App Builder instance and select `Hub` from the navigation on the left to enter your Local Hub. -2. Click the `Installed` button to open a pop-up window with the options to update or uninstall the bundle. -3. Click the `Uninstall` button. -4. An initial check is made to verify that components are not in use outside of the bundle. A pop-up window will list the components with external references that must be removed manually and then the uninstall process may be resumed^. +1. Log in to your App Builder instance and select `Hub` from the left navigation menu to enter your Local Hub. +2. Click the `Installed` button to open a pop-up window with the available options. +3. Click `Uninstall`. +4. An initial check is done to verify that components are not in use outside of the bundle. A pop-up window will list the components with external references that must be cleared manually, and then the uninstall process may resume. 5. When the `Uninstall` is confirmed, a progress bar shows the following removal process: - Bundle resources are deleted from the Entando App Engine - Components included in the bundle are removed from the Entando App Engine - - Plugins are unlinked + - Microservices are unlinked 6. To remove the bundle from the Local Hub catalog, click the `Undeploy` button. -^ When unistalling a PBC or any component with **multiple bundles**, it is important to remove the bundles in the reverse order of installation because of dependencies. +::: tip Uninstall Order +When unistalling a PBC or a Bundle Group with multiple bundles, it is important to remove the bundles in the reverse order of installation due to dependencies. +::: ## Troubleshooting If an error occurs during the uninstall process, check out the [Troubleshooting guide](./troubleshooting-guide.md) or the [Entando Forum](https://forum.entando.com). diff --git a/vuepress/docs/v7.3/docs/curate/bundle-component-details.md b/vuepress/docs/v7.3/docs/curate/bundle-component-details.md index 4857dc959e..e72a06b928 100644 --- a/vuepress/docs/v7.3/docs/curate/bundle-component-details.md +++ b/vuepress/docs/v7.3/docs/curate/bundle-component-details.md @@ -5,15 +5,15 @@ sidebarDepth: 2 # Bundle Component Descriptors -Elements such as pages, content, simple widgets, fragments, and static resources are classified as platform components on Entando. This page describes each of these elements with an example. +Elements such as pages, content, simple widgets, fragments, and static resources that belong to a bundle are classified as platform components on Entando. The following paragraphs describe each of these types and how they can be used in a bundle, with an example. Currently, Entando supports the following component types: ![component-types.png](./img/component-types.png) -Each component is defined by a descriptor YAML located in the bundle `platform` directory, inside the corresponding type as listed below. During the bundle pack phase, the descriptors are added to build the Docker images for the bundle. +Each is defined by a descriptor YAML placed in the corresponding folder inside the bundle `platform` directory. During the pack phase of building an Entando bundle, the descriptors are included in the resulting Docker image following this pattern. -Here is an example structure of a bundle project: +Here is an example structure of the `platform` directory in an Entando Bundle project: ``` bundle-project/ @@ -39,7 +39,7 @@ bundle-project/ ... entando.json <= Bundle project descriptor ``` ->Note: Older names `pageModels` and `contentModels` for `pageTemplates` and `contentTemplates`, respectively, are still supported on Entando 7 but may be removed in a future release. +>Note: Older names `pageModels` and `contentModels`, for `pageTemplates` and `contentTemplates` respectively, are still supported on Entando 7 but may be phased out in future releases. ## Assets The CMS asset descriptor contains the metadata required for uploading and updating bundle assets. @@ -69,7 +69,9 @@ This descriptor contains a list of categories. ## Contents This descriptor enables content to be created and published via a bundle, according to the `status` property. The content ID is optional and enables linking from other components, like content widgets. It can be auto-generated or explicitly declared. -Groups in a content descriptor are configured by the owner group `mainGroup` and the join group `groups`. The owner group consists of users who can manage the content within the App Builder, while the join group consists of users who can view the content. +Groups in a content descriptor are configured by the owner group `mainGroup` and the join group, `groups`. The owner group consists of users who can manage the content within the App Builder, while the join group consists of users who can view the content. + +See an example of [how content is created and managed](../../tutorials/compose/content-tutorial.md). **contents-descriptor.yaml** @@ -93,7 +95,9 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and - code: body values: en: | -

For many people, financial concerns are their number one stress point. Here are 6 ways to help reduce your money stress and get motivated to take control of your finances.

+

For many people, financial concerns are their number one stress point. + Here are 6 ways to help reduce your money stress and get motivated + to take control of your finances.

- code: img values: en: @@ -126,11 +130,12 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and correlationCode: '205' name: Entando_Admin_Console_Overview_4.3.3_EN.pdf -**^ Content Links** -* Content descriptors are loaded in alphabetical order during the bundle creation process. If content X references content Y, content Y must already exist in the bundle for the reference to work. To guarantee referential integrity in a bundle, we recommend that the descriptor name for Y appears earlier in the alphabetical order then content X. -* Contents in bundles cannot make circular references to another content through the link attribute. A circular link is when content A links to content B and B links back to A. Due to the descriptor's alphabetical order of installation, the circular link will cause an error but the links can be added manually after the installation of the bundle. +**^ Code: Links** +* Content descriptors are loaded in alphabetical order during the bundle creation process. If content X references content Y, content Y must already exist in the bundle for the reference to work. To guarantee referential integrity in a bundle, we recommend that the descriptor name for Y appear earlier in the alphabetical order then content X. +* Content in bundles cannot make circular references to each other through the link attribute. A circular link is when content A links to content B and B links back to A. Due to the descriptor's alphabetical order of installation, the circular link will cause an error, but the links can be added manually after the installation of the bundle. ## Content Templates +For some additional details, see the [Content Templates Tutorial](../../tutorials/compose/content-templates-tutorial.md). **contentTemplates-descriptor.yaml** @@ -138,10 +143,12 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and contentType: CNG description: Demo Content Template - # Optional. Define the content template shape in a separate file or inside the descriptor file with `contentShape` + # Optional. Define the content template shape in a separate file or inside + # the descriptor file with `contentShape` contentShapePath: - # Optional. Define the content template shape as shown below or in a separate file with `contentShapePath` + # Optional. Define the content template shape as shown below or in a separate file + # with `contentShapePath` contentShape: >-

$content.Title.text

@@ -179,7 +186,7 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and pos: 13 ## Content Types -For more details on content type properties, refer to the [Content Type documentation](../../tutorials/compose/content-types-tutorial.md). +For some more details, refer to the [Content Types Tutorial](../../tutorials/compose/content-types-tutorial.md). **contentTypes.yaml** @@ -233,6 +240,7 @@ For more details on content type properties, refer to the [Content Type document ognlExpression: string ## Fragments +See an example of [how to use a fragment](../../tutorials/compose/widgets-fragments.md#create-a-new-fragment). **fragments-descriptor.yaml** @@ -277,7 +285,9 @@ This descriptor contains a list of languages to enable during the installation p ## Pages This descriptor creates a page for a bundle. The page layout can be fully configured with a configuration widget. Page status can be `published` or `draft`. -Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The `ownerGroup` property specifies the group of users who can manage the entity in the App Builder. The `joinGroups` property specifies those who can view or access the page. For example, setting `ownerGroup` to "free" means anyone with access to the App Builder can manage the page, whereas setting `joinGroup` to "free" means any end user can view the page in the application. +Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The `ownerGroup` property specifies the group of users who can manage the page in the App Builder. The `joinGroups` property specifies those who can view or access the page. For example, setting `ownerGroup` to "free" means anyone with access to the App Builder can manage the page, whereas setting `joinGroup` to "free" means any end user can view the page in the application. + +See an example of [how a page is created and managed](../../tutorials/compose/page-management.md) in the App Builder. **pages-descriptor.yaml** @@ -325,6 +335,7 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The pos: 13 ## Page Templates +Here's some more details about [how page templates work on Entando](../../tutorials/compose/page-management.md#create-a-page-template). **pageTemplate-descriptor.yaml** @@ -346,14 +357,16 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The x2: 11 y2: 1 defaultWidget: - code: my-widget # The widget code to apply when using the button "apply default widgets" in the page configuration UI + code: my-widget # The widget code to apply when using the button + # "apply default widgets" in the page configuration UI # A simplified way to define frames - pos: 1 description: Breadcrumb sketch: { x1: 0, y1: 0, x2: 11, y2: 1 } - # Optional. Define the page template in a separate file or inside the descriptor file with `template` + # Optional. Define the page template in a separate file or inside the descriptor file + # with `template` templatePath: page.ftl # Optional. Define the page template as below or in a separate file with `templatePath` @@ -375,7 +388,9 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The ## Static Resources -The `resources` folder in the `platform` directory contains all static resources. These files will be uploaded to Entando using the same structure, found in the App Builder File Browser public folder. +The `resources` folder in the `platform` directory contains all static resources. Once the bundle is installed, they can be found inside the App Builder File Browser, with the same file structure. + +See which [digital formats are supported on Entando](../../tutorials/compose/digital-assets-tutorial.md). ``` platform/ ... @@ -399,9 +414,9 @@ To use static files in a Widget or Page Template, use the FTL tag `<@wp.resource ``` ent ecr get-bundle-id repo=url ``` -It should return an 8 digit string of numbers and letters, e.g. bundle-id=8785d979. +It should return an 8 digit string of numbers and letters, e.g. BUNDLE-ID=8785d979. -2. YOUR-BUNDLE-CODE is YOUR-BUNDLE-NAME-YOUR-BUNDLE-ID: +2. YOUR-BUNDLE-CODE is YOUR-BUNDLE-NAME appended with YOUR-BUNDLE-ID: If YOUR-BUNDLE-NAME=first-bundle and YOUR-BUNDLE-ID=8785d979, then YOUR-BUNDLE-CODE=first-bundle-8785d979 @@ -435,9 +450,11 @@ Here are example tags to access static resources in a typical bundle: # Optional. The configUI configUi: - customElement: my-widget-config # The name of the custom element used to render the configUi + customElement: my-widget-config # The name of the custom element used to render + # the configUi resources: - - /static/js/main.js # The resources necessary for the custom element to render the configUI, like the code + - /static/js/main.js # The resources necessary for the custom element to + # render the configUi, i.e., the code **Note**: To configure micro frontends to access static assets, Entando provides a path with the following snippet: ``` js diff --git a/vuepress/docs/v7.3/docs/curate/bundle-details.md b/vuepress/docs/v7.3/docs/curate/bundle-details.md index a63433a0fb..986f5fa3fc 100644 --- a/vuepress/docs/v7.3/docs/curate/bundle-details.md +++ b/vuepress/docs/v7.3/docs/curate/bundle-details.md @@ -2,18 +2,18 @@ sidebarDepth: 2 --- -# Entando Bundle +# The Entando Bundle -The structure of an Entando Bundle leverages composable development methods, decoupling microservices, micro frontends, API management, and services such as databases. The **ent bundle CLI** module administers the process, using the descriptor `entando.json`. This single bundle descriptor defines all the components and resources of the docker-based bundle. The following page describes the descriptor, the structure, its conventions, and the building process. +The Entando Bundle is the smallest building block from which applications are built on Entando. It leverages composable development methods, decoupling microservices, micro frontends, and APIs to make it modular and easier to containerize. The **ent bundle CLI** administers the process, using a single descriptor `entando.json` to define the docker-based bundle. This page describes the Entando Bundle structure, the descriptor file, its conventions, and the packaging process. The docker-based approach is an improvement on the previous Entando Bundle structure and to see the differences, refer to the [Bundle Evolution](../reference/bundle-comparison.md) page. ## Entando Bundle Conventions * There is a single bundle descriptor, `entando.json`, initialized and managed by the [ent bundle CLI](../getting-started/ent-bundle.md). -* Microservices and micro frontends can be built independently, each with their own folders. -* The `platform` directory is dedicated to platform specific components such as fragments, pages, and static resources. For more information on component types and descriptors, see the [Bundle Component Details](bundle-component-details.md) page. -* The `svc` directory is allocated for auxiliary services and the docker-compose configuration files that define them. The ent bundle module enables, starts and stops the services. MySQL, PostgreSQL, and Keycloak services are available with Entando out of the box, and for more details, go to the [ent CLI Services page](../getting-started/ent-svc.md). +* Microservices (MSs) and micro frontends (MFEs) are built and processed independently, with a Docker image for the bundle and for each MS. +* The `platform` directory is dedicated to project specific components such as fragments, pages, and static resources. For more information on component types and corresponding descriptors, see the [Bundle Component Details](bundle-component-details.md) page. +* The `svc` directory is allocated for auxiliary services and the docker-compose configuration files that define them. The ent bundle commands enable, start and stop the services. MySQL, PostgreSQL, and Keycloak services are available with Entando out of the box, and for details on adding custom services, go to the [ent Bundle CLI Services page](../getting-started/ent-svc.md). * Optionally, a thumbnail for your bundle can be set by adding a JPG or PNG image file to the bundle root folder. The file must be named "thumbnail" and be 100kb or less, e.g. thumbnail.png. ## Project Structure @@ -53,9 +53,9 @@ platform/ <= platform specific components ![Bundle Development Process](./img/development-process.jpg) -The ent bundle CLI module manages the building and publishing of an Entando Bundle. From initialization to installation, from adding MFEs and MSs to calling for services such as Keycloak and making API claims, the ent bundle commands streamline the development process. +The ent bundle CLI module manages the building and publishing of an Entando Bundle. From initialization to installation, from adding MFEs and MSs to calling for services and making API claims, the ent bundle commands streamline the development process. -At initialization, the project scaffolding is built. A project can be started from scratch with this structure or retrieved interactively from an Entando Hub as a starting point for new bundles. Microservices, micro frontends, components, services, and API claims can then be added. At this stage, components can be run locally and independently with the ent bundle commands. +At initialization, the project scaffolding is built. A project can be started from scratch with this structure or downloaded interactively from an Entando Hub with the `ent bundle init --from-hub` command. Microservices, micro frontends, components, services, and API claims can then be added, manually or with the ent bundle CLI. At this stage, components can be run locally and independently. The next steps build and pack the project using the bundle descriptor. The specifics depend on the component type and stack. The build phase constructs the microservices and micro frontends while the pack command generates the artifacts and Docker images. Images are built for the bundle and for each microservice. @@ -63,9 +63,9 @@ In the publish step, images are pushed to a Docker registry and tagged according ![Bundle Publishing Process](./img/publishing-process.jpg) -Finally, the bundle is deployed into the Local Hub of a running Entando instance where it can then be installed. Any improvements to the bundle can be made by repeating the **four steps: pack, publish, deploy and install**. Alternatively, the install step can be done in the App Builder UI by the composer designing the application. +Finally, the bundle is deployed into the Local Hub of a running Entando instance where it can be installed. Any improvements to the bundle can be made by repeating the **four steps: pack, publish, deploy and install**. Alternatively, the install step can be completed in the App Builder UI when composing an application by upgrading the version. -At every phase of the process, options are available to fine-tune the process, and to see more information, go to the [ent bundle CLI](../getting-started/ent-bundle.md) documentation. +At every phase of the process, options are available to fine-tune the process, and for more specifics, see the [ent bundle CLI](../getting-started/ent-bundle.md) documentation. ## Bundle Descriptor entando.json The following is a list of specifications for the bundle descriptor and its component parts. @@ -73,13 +73,13 @@ The following is a list of specifications for the bundle descriptor and its comp ### Bundle Descriptor Specifications |Name|Type|Required|Description| |:---|:---|:-|:-----------------------| -|`description`|String| No |A description of the bundle project shown in the App Builder| +|`description`|String| No |A description of the bundle project displayed in the App Builder| |`displayName`|String|No|A descriptive label used in the UI in place of a name| |`global`|[Global[]](#global-specification)|No|Global bundle configuration items| |`microfrontends`|[Micro Frontends](#micro-frontends-specifications)|No|Bundle micro frontends| |`microservices`|[Microservices](#microservices-specifications)|No|Bundle microservices| |`name^`|String|Yes|The bundle project name used as the default Docker image name| -|`version`|String|Yes|The bundle version used as the default Docker image tag| +|`version`|String|Yes|The bundle version used in the default Docker image tag| ^ Bundle Name: A bundle name may only contain lowercase letters, numbers, periods(.), and dashes(-). They cannot start or end with periods or dashes. ```json @@ -111,7 +111,7 @@ The following is a list of specifications for the bundle descriptor and its comp |`stack`|Enum|Yes|*spring-boot
*node
*custom|Microservice stack | |`version`|String|Required only for a custom stack||Microservice version override| -**^ dbms none**: Oracle and other DBMS types are not supported for automatic deployment in a container. Bundle env variables should be used instead, similar to connecting the EntandoApp to an [external database](../../tutorials/devops/external-db.md). +**^ dbms none**: Oracle and other DBMS types are not supported for automatic deployment in a container. Bundle env variables should be used instead, similar to this instance of an [external database](../../tutorials/devops/external-db.md). #### Microservices Sample Code ```json @@ -147,7 +147,7 @@ The following is a list of specifications for the bundle descriptor and its comp - To utilize **environment variables**, inline or based on Kubernetes Secrets, see the [Plugin Environment Variables](../../tutorials/devops/plugin-environment-variables.md) tutorial. - - Entando uses the `healthCheckPath` to monitor the health of the microservice. A plugin in an Entando Bundle can use any technology, as long as it provides a health check service configured via the `healthCheckPath`. This path must be specified in the descriptor file and return an HTTP 200 or success status. This can be implemented by a Java service included with the Entando Blueprint in the Spring Boot application. You can also [use a Node.js service as shown here](https://github.com/entando-samples/ent-project-template-node-ms/blob/main/src/main/node/controller/health-controller.js). + - Entando uses the `healthCheckPath` to monitor the health of the microservice. A plugin or microservice in an Entando Bundle can use any technology, as long as it provides a health check service configured via the `healthCheckPath`. This path must be specified in the descriptor file and return an HTTP 200 or success status. This can be implemented by a Java service included with the Entando Blueprint in the Spring Boot application. You can also [use a Node.js service as shown here](https://github.com/entando-samples/ent-project-template-node-ms/blob/main/src/main/node/controller/health-controller.js). ### Micro Frontends Specifications |Name|Type|Required|Possible Values|Description| @@ -160,18 +160,18 @@ The following is a list of specifications for the bundle descriptor and its comp |`contextParams`|String[]| Yes | | Information extracted from the application context | |`group`|String|Yes||Visibility group name| |`name`|String|Yes||Micro frontend name| -|`stack`|Enum|Yes|*react
*angular
*custom|MFE stack| -|`type`|Enum|Yes|*widget *widget-config *app-builder|Type of MFE| |`nav`|[MenuEntry[]](#menuentry-specification)|No||Bundle menu global links| |`params`| [MfeParam[]](#mfeparam-specification) |Yes| | User configuration for executing a widget| |`paths`|String[]|Yes for `type=app-builder` and `slot=content`||App Builder activation paths| |`publicFolder`|String|No|Default is `public`|MFE public folder (typically where index.html is located)| |`slot`|Enum|Yes for `type=app-builder`|*primary-header *primary-menu *content|Named reference to an App Builder embedded position in a specific layout| +|`stack`|Enum|Yes|*react
*angular
*custom|MFE stack| |`titles`|String[]|Yes for `type=widget`||Localized widget labels| +|`type`|Enum|Yes|*widget *widget-config *app-builder|Type of MFE| |`version`|String|Required only for custom stack MFE||Microfrontend version override| #### Configure a Path for Static Assets -To configure your micro frontend with access to static assets, Entando provides two paths, one for widgets and another for EPCs. +To configure your micro frontend with access to static assets, Entando provides two paths, one for widgets and another for [Entando Platform Capabilities (EPCs)](../../tutorials/create/mfe/epc.md). * For widgets: `window.entando?.widgets['YOUR-MFE']?.basePath;` @@ -216,7 +216,7 @@ A custom `category` provides an organizing classification for `Widgets`, to appe ### API Claim Specification |Name|Type|Required|Possible Value|Description| |:-|:-|:-|:-|:------------------------| -|`bundle`|String|Yes only for `type=external`||Bundle Docker URL| +|`bundle`|String|Yes only for `type=external`||Bundle Docker URL| |`name`|String|Yes||Name| |`serviceName`|String|Yes||The name of the microservice| |`serviceUrl`| String| No ||The URL of the microservice deployed in the local environment| @@ -238,25 +238,21 @@ A custom `category` provides an organizing classification for `Widgets`, to appe } ] ``` -For more information, go to the [API Management](../getting-started/ent-api.md) page. +For more information, see the [API Management](../getting-started/ent-api.md) page. ### Command Specification -|Name|Type|Required| Description| -|:-|:-|:-|:------------------------| -|`build`|String|No| Custom build command| -|`pack`|String|No| Custom pack command| -|`run`|String|No| Custom run command| +|Name|Type|Required| Default (Stack dependent) | Description| +|:-|:-|:-|:-|:------------------------| +|`build`|String|No| mvn test, npm run test | Custom build command| +|`pack`|String|No| mvn spring-boot:run, npm run start | Custom pack command| +|`run`|String|No| mvn package, npm run build | Custom run command| -#### Command Spec Sample Code +#### Custom Command Sample Code ```json "commands": { "run": "mvn -Dspring-boot.run.arguments=\"--server.port=8082\" spring-boot:run" } ``` -Depending on the stack type, default values are: -- build: mvn test, npm run test -- run: mvn spring-boot:run, npm run start -- pack: mvn package, npm run build ### EnvironmentVariables Specification |Name|Type|Required|Description| @@ -304,12 +300,12 @@ Depending on the stack type, default values are: The following are platform-provided runtime variables. |Name| Type | Description| |:-|:---|:----------------------------------| -|`ENTANDO_TENANT_CODE`| string | For multitenant environments only, automatically inserted to identify the owner tenant | +|`ENTANDO_TENANT_CODE`| string | For multitenant environments only, automatically inserted to identify the owner tenant. | |`KEYCLOAK_REALM`| string | Keycloak or Red Hat Single Sign-On (RH-SSO) realm to be used by the MS. | |`KEYCLOAK_AUTH_URL` | string | Keycloak/RH-SSO URL to be used by the MS.| |`KEYCLOAK_CLIENT_SECRET`| `secretKeyRef[]`| Keycloak/RH-SSO autogenerated clientSecret to be used by the MS. | | `KEYCLOAK_CLIENT_ID`| `secretKeyRef[]`| Keycloak/RH-SSO autogenerated clientId to be used by the MS. | -|`SERVER_SERVLET_CONTEXT_PATH` | string | Context path used to access the MS. Automatically handled by a Spring Boot MS, but can be manually set for other `stack` types.| +|`SERVER_SERVLET_CONTEXT_PATH` | string | Context path used to access the MS. Automatically handled by a Spring Boot MS but can be manually set for other `stack` types.| | `SPRING_PROFILES_ACTIVE`| string | Application profile to use when the MS runs on Entando, differentiating dev vs prod at runtime. Automatically handled by a Spring Boot MS but can be manually managed if using another technology `stack`. | | `SPRING_DATASOURCE_URL`| string| Provisioned database JDBC connection URL. Automatically handled by a Spring Boot MS but can be manually managed if using another technology `stack`. | | `SPRING_DATASOURCE_USERNAME` | string| Provisioned database username. Automatically handled for a Spring Boot MS, but can be manually managed if using another technology `stack`.| diff --git a/vuepress/docs/v7.3/docs/curate/bundle-filters.md b/vuepress/docs/v7.3/docs/curate/bundle-filters.md index c49a7f808b..1f0b75cc18 100644 --- a/vuepress/docs/v7.3/docs/curate/bundle-filters.md +++ b/vuepress/docs/v7.3/docs/curate/bundle-filters.md @@ -1,12 +1,15 @@ +--- +sidebarDepth: 2 +--- # Filtering Bundles -Entando Bundles are filterable by component, status or textual search from the App Builder user interface. +Entando Bundles can be filtered by its status, component part, or textual search from the App Builder user interface. ![App Builder bundle filtering](./img/bundle-filtering.png) ## Filtering Bundles by Component -To filter a bundle by component, its custom resource on the Entando Cluster must contain appropriate labels. Valid labels are: widget, plugin, fragment, pageTemplate, contentType and contentTemplate. To correctly define a label in a K8s resource requires both a key and value, but Entando uses only the key when filtering. Although the value is arbitrary, we recommend a setting of `"true"` for clarity and simplicity. +To filter a bundle by component, its custom resource in the Entando Cluster must contain appropriate labels. Valid labels are: widget, plugin, fragment, pageTemplate, contentType and contentTemplate. To correctly define a label in a K8s resource requires both a key and value, but Entando uses only the key when filtering. Although the value is arbitrary, we recommend a setting of `"true"` for clarity and simplicity. ### Supported Labels Keys @@ -68,13 +71,13 @@ spec: ## Filtering Bundles by Status -Entando Bundles are filterable by availability and install status. Select the `Explore` tab to see the full list of bundles available in the Kubernetes cluster. Select the `Installed` tab to see the list of currently installed bundles. +Entando Bundles are filterable by availability and install status. Select the `Explore` tab to see the full list of bundles available in the Kubernetes cluster. Select the `Installed` tab to see the list of currently installed bundles in the Local Hub of the App Builder. ## Filtering Bundles by Textual Search -Use the textual search to return bundles that contain certain keywords in their name, description or version. When creating a new bundle, bear in mind that a textual search is performed against data extracted from the bundle CRD file. +Use the textual search to return bundles that contain certain keywords in their name, description or version. When creating a new bundle, bear in mind that a textual search is performed against data extracted from the bundle custom resource definition. ## Mixing Search Criteria -Filtering can be refined by combining component, status and textual search criteria. For example, you could search for all available bundles (filter by status) that contain `Page Templates` (filter by component) and the word `Login` in their name (filter by textual search). +Filtering can be refined by combining component, status and textual search criterias. For example, you could search for all available bundles (filter by status), that contain `Page Templates` (filter by component), with the word `Login` in the name (filter by textual search). diff --git a/vuepress/docs/v7.3/docs/curate/bundle-presentation-config.md b/vuepress/docs/v7.3/docs/curate/bundle-presentation-config.md index d41be3070b..db6b2df82c 100644 --- a/vuepress/docs/v7.3/docs/curate/bundle-presentation-config.md +++ b/vuepress/docs/v7.3/docs/curate/bundle-presentation-config.md @@ -1,11 +1,16 @@ +--- +sidebarDepth: 2 +--- # Customize Bundle Info Shown in App Builder -An example of how bundles are displayed in the Local Hub of the App Builder is shown below: +To modify what is displayed for your bundles in the Local Hub, there are a few specifications that can be customized. This is helpful when there are many bundles or they are shared across teams and organizations. + +Bundles are typically displayed in the Local Hub of the App Builder like this: ![Hub user interface in Entando App Builder](./img/local-hub-page.png) -The corresponding custom resource file on Kubernetes contains content similar to the following: +The corresponding Kubernetes custom resource file looks similar to this: ``` apiVersion: entando.org/v1 @@ -32,10 +37,10 @@ spec: version: 0.0.1 ``` -Spec Definitions: +These are the specifications that can be customized: | Field | UI Element | -|---------------------------------|---------------------------------------------------------------------------| -| `spec.details.name` | Set the bundle title | -| `spec.details.description` | Set the bundle description (only visible in list format) | -| `spec.details.dist-tags.latest` | Set the latest version of the bundle | \ No newline at end of file +|-------------------------|---------------------------------------------------------------------------| +| `spec.details.name` | The bundle title | +| `spec.details.description` | The bundle description (only visible in list format) | +| `spec.details.dist-tags.latest` | The latest version of the bundle | \ No newline at end of file diff --git a/vuepress/docs/v7.3/docs/curate/bundle-versions-faq.md b/vuepress/docs/v7.3/docs/curate/bundle-versions-faq.md index 0d2596292e..aac51221a5 100644 --- a/vuepress/docs/v7.3/docs/curate/bundle-versions-faq.md +++ b/vuepress/docs/v7.3/docs/curate/bundle-versions-faq.md @@ -2,23 +2,22 @@ sidebarDepth: 1 --- -# Bundle Versions and Updates - FAQ +# Bundle Versions - FAQ ## Support ### 1. Does the Entando Platform support bundle versioning? -A bundle is an independent package containing one or more components. -As in other packaging systems, the [Entando Component Registry](../compose/local-hub-overview.md)(ECR) supports bundle versioning, allowing developers to create and release updates of their package over time. +A bundle is a self-contained package containing one or more components such as microservices and micro frontends. As in other packaging systems, the [Entando Component Registry](../compose/local-hub-overview.md) (ECR) supports bundle versioning, allowing developers to create and release updates of their package over time. ## How-Tos ### 1. How do I create a new version of a bundle? -To release new versions of your bundle after changes have been made, edit the `entando.json` with the new version number for the bundle, then pack and publish your images to Docker. Docker will provide tags to update the bundle version. Once you deploy and install the bundle, the new version number will appear in the App Builder. +To release new versions of your bundle after changes have been made, edit the `entando.json` with the new version number, then pack and publish your images to Docker. Docker will provide tags to update the bundle version. Once you deploy and install the bundle, the new version number will appear in the App Builder. Micro frontends and microservices can have their own version numbers, independent of the bundle version, and can be updated in the same way. ### 2. My bundle contains a microservice generated with the Entando Component Generator; does the version of the microservice have to be the same as the bundle version? -The version of the microservice - or the Docker image associated with the microservice - isn't bound to the version of the bundle containing the microservice itself. +The version of the microservice - or the Docker image associated with the microservice - isn't bound to the version number of the bundle it is a part of. Thus, the same microservice can be used in different bundles. This gives the developer control over the bundle release process, especially in situations where the bundle may contain many components. @@ -27,7 +26,7 @@ This gives the developer control over the bundle release process, especially in ### 1. How is a bundle version defined? -Bundle versions are defined by the creator and set in the bundle descriptor `entando.json`. You can have multiple versions of a bundle as long as they are defined and tagged as such. +Bundle versions are defined by the creator and set in the `entando.json` bundle descriptor. You can have multiple versions of a bundle as long as they are defined and tagged as such. ```json { @@ -49,9 +48,9 @@ Follow the recommended [semantic versioning 2.0.0](https://semver.org/#semantic- ### 3. Can I publish all versions of any bundle to my Local Hub for development? -To make all versions for all bundles available in the Local Hub, edit the environment variable `ENTANDO_BUNDLE_TAGS_TYPES` in the component manager (CM) deployment to have the value, `dev,prod`. Tag types can also be set to `dev` or `prod`. +To make all versions for all bundles available in the Local Hub, edit the environment variable `ENTANDO_BUNDLE_TAGS_TYPES` of the Entando Component Manager (ECM) deployment to have the value, `dev,prod`. Tag types can also be set to only `dev` or `prod`. -For individual bundles, see the [Bundle Management page](../getting-started/ent-bundle.md#generate-cr) for details about how to utilize the ent CLI's bundle commands to select development, production, or both types of bundles. +For individual bundles, see the [Bundle Management page](../getting-started/ent-bundle.md#generate-cr) for details about how to utilize the ent CLI's bundle commands to select for development, production, or both types of bundles. diff --git a/vuepress/docs/v7.3/docs/curate/hub-details.md b/vuepress/docs/v7.3/docs/curate/hub-details.md index 2a8c231f6f..b46e805043 100644 --- a/vuepress/docs/v7.3/docs/curate/hub-details.md +++ b/vuepress/docs/v7.3/docs/curate/hub-details.md @@ -4,54 +4,54 @@ sidebarDepth: 2 # Entando Hub Features and Definitions ## Overview -The Entando Hub is the central catalog where components are published, organized and shared. The reusable components called Bundle Groups come with versioning and publishing management capabilites in the Hub UI. The following describes the details of how this process is defined and accomplished. +The Entando Hub is the central catalog where components are published, organized and shared. When building composable applications, building blocks called bundles or bundle groups are chosen from this catalog and placed onto a page. The Hub UI provides publishing and versioning capabilites for these reusable components and the following describes the details of how this process works. -Entando Hub Features: +**Entando Hub Features:** -- Centralize components and business capabilities for use across teams, groups, or clients +- Centralize components and packaged business capabilities (PBCs) for use across teams, projects, or clients - Publish and manage components, and communicate component features, versions and metadata -- Perform business-level assessment of component readiness +- Perform business-level assessments of component readiness -The Hub can be utilized in several ways in any Entando Application: -* The **Local Hub**, included in the Entando App Builder, displays a collection of ready-to-use components. They can be used to compose an application or as a starting point to create new components. +The Entando Platform provides three variations of the catalog. They are all directly accessible from the App Builder to make it easy to find and select the components to build your applications. -* **Entando Cloud Hub** is the public catalog containing packaged business capabilities and components provided by Entando and its partners throughout the world. +* The **Local Hub**, included in the Entando App Builder, displays a collection of ready-to-use components. They can be used to compose an application or as a starting point to create your own. -* **Enterprise Entando Hub**, applied and curated by Entando clients and partners, it can be used to share components within their respective organizations or made available for public use. +* **Entando Marketplace** is the public catalog presenting the packaged business capabilities and components developed by Entando and its partners throughout the world. -[Installation and User Guide](../../tutorials/solution/entando-hub.md) +* The **Enterprise Entando Hub** can be added to your Entando instance for your organization to share components, privately within teams, with clients, or with the public. + +The remainder of this document explores the parameters of the Enterprise Hub, and to see how it is installed, here is the [Installation and User Guide](../../tutorials/solution/entando-hub.md). ## Bundle Group Definitions -The key entities in an enterprise Hub are: +The key entities in a Hub are as follows: -- `Bundle Group`: A Bundle Group is a Hub entry, a single unit containing one or more Entando Bundles. -- `Bundle`: An Entando Bundle is the deployment unit within an Entando Application. A bundle can contain one or more components such as micro frontends, microservices, or any of the [component types](../../docs/curate/bundle-component-details.md) allowed in Entando. -- `Bundle Group Version`: A Bundle Group can have one or more versions, each with a particular status. -- `Category`: Each Bundle Group belongs to a specific category. The default categories are solution template, packaged business capability (PBC), and component collection. An admin of an enterprise Hub can create and refine the categories as desired. -- `Organization`: Bundle Groups belong to a single organization. Authors and managers can only update entries within their own organization. A single instance of the Hub can have multiple organizations. +- `Bundle`: An Entando Bundle is the basic deployment unit within an Entando Application. A bundle can contain one or more component such as micro frontends, microservices, or any of the [component types](../../docs/curate/bundle-component-details.md) allowed on Entando. +- `Bundle Group`: A bundle group is a Hub entry, a single unit containing one or more Entando Bundle. +- `Bundle Group Version`: A bundle group can have one or more versions, each with a particular status. +- `Category`: Each bundle group belongs to a specific category. The default categories are solution template, packaged business capability (PBC), and component collection. Additional categories can be customized for any Enterprise Hub. +- `Organization`: Bundle groups belong to a single organization. Authors and managers can only update entries within their own organization. A single instance of the Hub can have multiple organizations. - `User`: User identity is managed within Keycloak, where users are granted roles within a Hub instance. Users must be created in Keycloak, then added in the Hub and assigned to a specific organization. - -> A private repository can be used for a bundle, but this requires [an additional Kubernetes Secret](../../tutorials/curate/private-git-repo.md) before deployment via the App Builder. +> A private repository can be the source of a bundle, but this requires [an additional Kubernetes Secret](../../tutorials/curate/private-git-repo.md) before deployment in the App Builder. ## Roles -Three roles are defined to provide access to the enterprise Hub features: +Three roles are available for the Enterprise Hub UI to manage its catalog. All roles are tied to an organization and are defined as follows: -- `eh-author`: An author can create and edit Bundle Groups for their organization and submit them for publication. They can generate an API key. -- `eh-manager`: A manager has the capabilities of an author, but can also approve a publication request for their organization. -- `eh-admin`: An admin has full access to create, update, and delete Bundle Groups and manage users for the entire Hub instance. An admin can also create categories, organizations and private catalogs, assign users to organizations, and generate API keys. -- `guest`: Any user without one of the preceding roles is considered a guest in the enterprise Hub and is given a read-only view of the public catalog. This is also true for unauthenticated users. +- `eh-author`: An author can create and edit bundle groups and submit them for publication. They can also generate an API key for private Hubs. +- `eh-manager`: A manager has all the capabilities of an author, but also has the job of approving bundle groups for publication. +- `eh-admin`: An admin has full access to create, update, approve, and delete bundle groups, and manage users for the entire Hub instance. An admin can create categories, organizations and private catalogs, assign users to organizations, and generate API keys for private catalogs. +- `guest`: Any user without one of the preceding roles is considered a guest in the Enterprise Hub and is given a read-only view of a public catalog. This is also true for unauthenticated users. To assign roles to a new Hub user, see the [Entando Hub Installation and User Guide](../../tutorials/solution/entando-hub.md#user-management) ## Bundle Group Versions -The list of Bundle Group versions can be seen by clicking `View Versions` for any entry in the catalog: +Available bundle group versions can be viewed or edited from the kebab-dropdown menu of an entry as seen here: ![hub-actions.png](./img/hub-actions.png) -The following rules apply to Bundle Group versions: +The following versioning rules apply to bundle groups: - Once the first version of a group is published, the organization, name, and category can no longer be changed. -- A new version of a Bundle Group can be created (via the `New Version` option) after the first version has been published. +- A new version of a bundle group can be created only after the first version has been published. - There can be at most two active versions: one draft or publication requested version, and one published version. - When a new version is published, the previous version is set to `Archived`. - Archived versions are only visible in the versions view and are not shown elsewhere in the user interface. @@ -60,24 +60,24 @@ The following rules apply to Bundle Group versions: ## Bundle Group Status -The possible statuses for each version of a Bundle Group are as follows: +The possible statuses for each version of a bundle group are as follows: -- `Draft`: This is the default status for the first version of a Bundle Group. -- `Publication Request`: An `eh-author` sets a version to this status to request the `eh-manager` or `eh-admin` to review the version and approve it for publication. The manager or admin may also edit versions with this status. -- `Published`: Versions with this status are visible in the home page catalog of available Bundle Groups, and are also available in the App Builder-facing API. An `eh-manager` or `eh-admin` may edit published versions. +- `Draft`: This is the default status for a newly created bundle group. +- `Publication Request`: An `eh-author` sets a version to this status to request the `eh-manager` or `eh-admin` to review and approve it for publication. The manager or admin may edit versions with this status. +- `Published`: Versions with this status are visible in the Hub's catalog of available bundle groups, and are also available in the App Builder-facing API. An `eh-manager` or `eh-admin` may edit published versions. - `Archived`: Previously published versions are assigned this status. No edits can be made to an archived version. -- `Deletion Request`: An `eh-manager` or `eh-admin` can delete versions once this status has been set. +- `Deletion Request`: An `eh-manager` or `eh-admin` can delete versions once a group has been assigned this status. Notes: - An `eh-author` can change any field except organization while a version is in `Draft` status. -- There is no automated notification process when a publication request is made for a Bundle Group version. +- There is no automated notification process when a publication request is made for a bundle group version. -## Application Details +## Entando Hub Application Details -An Entando Hub includes the following key components: +An Enterprise Entando Hub includes the following key components: #### Micro Frontends / Widgets -- `Entando Hub App`: This is the main micro frontend which contains the management UI for the Hub entities noted above. +- `Entando Hub App`: This is the main micro frontend which contains the management UI for the catalog noted above. - `Entando Hub Login`: This is an optional login component which can be used in a page’s top navigation. #### Microservices diff --git a/vuepress/docs/v7.3/docs/curate/img/publishing-process.jpg b/vuepress/docs/v7.3/docs/curate/img/publishing-process.jpg index 971adc1d50..e19e3b37fd 100644 Binary files a/vuepress/docs/v7.3/docs/curate/img/publishing-process.jpg and b/vuepress/docs/v7.3/docs/curate/img/publishing-process.jpg differ diff --git a/vuepress/docs/v7.3/docs/curate/troubleshooting-guide.md b/vuepress/docs/v7.3/docs/curate/troubleshooting-guide.md index 4a701ae078..0f85003d9f 100644 --- a/vuepress/docs/v7.3/docs/curate/troubleshooting-guide.md +++ b/vuepress/docs/v7.3/docs/curate/troubleshooting-guide.md @@ -1,30 +1,33 @@ -# Troubleshooting ECR +--- +sidebarDepth: 2 +--- +# Troubleshooting the Entando Local Hub -## How do I access the logs? +## 1. How do I access the logs? **A bundle installation or removal has failed. How do I access the logs?** -The Entando Component Manager (CM) logs can be viewed using CLI tools like kubectl or oc, or visualization dashboards like OpenShift or K9s. +The Entando Component Manager (ECM) logs can be viewed using CLI tools like kubectl or oc, or visualization dashboards like OpenShift or K9s. ### Solution -1. To view the Component Manager logs, find the CM pod name in your instance: +1. To view the Component Manager logs, find the ECM pod name in your instance: ``` ent kubectl get pods ``` -It will be something like this: `quickstart-cm-deployment-7f74757f97-xnlbn` +It should be something like this: `quickstart-cm-deployment-7f74757f97-xnlbn` -2. Using your CM pod name and namespace, use this command to view the logs: +2. Using the ECM pod name and your namespace, use this command to view the logs: ``` -ent kubectl logs -f YOUR-PODNAME-7f74757f97-xnlbn -n YOUR-NAMESPACE +ent kubectl logs -f YOUR-ECM-PODNAME -n YOUR-NAMESPACE ``` >Notes: >1. Use the [ent CLI](../getting-started/entando-cli.md) to send commands directly to Kubernetes from the host machine. >2. The `-f` flag is optional and used to follow the logs for debugging purposes. The namespace (-n) is also optional if ent has a profile configured. -## ERROR - File not found in bundle +## 2. ERROR - File not found in bundle **Installation fails because a file has not been found in the bundle** -When a component referenced in the entando.json is missing or not properly called, the bundle installation fails and the error is reported in the logs. +When a component referenced in the `entando.json` is missing or not properly called, the bundle installation fails and the error is reported in the logs. ``` ERROR - File with name {filename} not found in the bundle @@ -34,19 +37,19 @@ ERROR - File with name {filename} not found in the bundle Verify that the component named in the descriptor file is actually at the specified location and the reference is properly formatted. Then, publish the updated bundle with `ent bundle publish`. -## My plugin Docker image is unreachable +## 3. My microservice's Docker image is unreachable **Bundle installation fails due to plugin images that are not reachable** -A bundle installation does not complete successfully because a plugin in a bundle, defined by a Docker image, is not available. +A bundle installation does not complete successfully because a microservice in a bundle, defined by a Docker image, is not available. ### Solution -This may happen if the Docker image for the plugin is located in a private registry or not yet published. Verify that the Docker image you are referencing is published, correctly formatted, and publicly available. Then, publish the updated bundle with `ent bundle publish`. +This may happen if the Docker image for the microservice is located in a private registry or not yet published. Verify that the Docker image you are referencing is published, correctly formatted, and publicly available. -## How do I uninstall a bundle +## 4. How do I uninstall a bundle **I can't uninstall a bundle because some components are in use** -When uninstalling an installed bundle, the Entando Component Manager verfies that the bundle components are not in use by any other component. An error message informs you and does not allow the removal. +When uninstalling a previously installed bundle, the Entando Component Manager verifies that the bundle components are not in use elsewhere. If any part of the bundle is in use, an error message informs you and does not allow the removal. ### Solution -A bundle cannot be uninstalled if any of its components are in use. To uninstall the bundle, the user must manually remove all references to it and all its component. \ No newline at end of file +A bundle cannot be uninstalled if any of its components are in use. To uninstall the bundle, the user must manually remove all references to it and its component parts. \ No newline at end of file diff --git a/vuepress/docs/v7.3/docs/curate/uninstall-flow.md b/vuepress/docs/v7.3/docs/curate/uninstall-flow.md index b0a4fdbe22..1380c6b078 100644 --- a/vuepress/docs/v7.3/docs/curate/uninstall-flow.md +++ b/vuepress/docs/v7.3/docs/curate/uninstall-flow.md @@ -1,26 +1,31 @@ +--- +sidebarDepth: 2 +--- # Bundle Upgrade, Downgrade, and Uninstall -An application bundle that has been installed in the Entando App Builder can be upgraded to a new version, reverted to a previous version or uninstalled at any time. You can update the bundle or just a component within that bundle, all within the App Builder. +An application bundle that has been installed in the Entando App Builder can be removed, upgraded to a new version, or downgraded to a previous version at any time. You can update the bundle group or just a component within that bundle. ## Upgrade or Downgrade Bundle Version -1. Log in to your App Builder instance and select `Hub` from the navigation on the left to enter your Local Hub. +1. Log in to your App Builder instance and select `Hub` from the left navigation bar to go to your Local Hub. 2. Click the `Installed` button to open a pop-up window with the options to update or uninstall the bundle. -3. Click the `Update` button to see a list of versions available. Choose a version. A warning will appear regarding the possible loss of features or data with the update. You may wish to review the bundle's release notes before confirming the upgrade or rollback. +3. Click the `Update` button to see the list of available versions. Choose one and a warning will appear regarding the possible loss of features or data with the update. You may wish to review the bundle's release notes before confirming the upgrade or rollback. 4. Once you confirm, a page listing all the components in the bundle appears. You can `Update All` or select each component to be updated or skipped. 5. Click `Ok` to finish. ## Uninstall a Bundle -1. Log in to your App Builder instance and select `Hub` from the navigation on the left to enter your Local Hub. -2. Click the `Installed` button to open a pop-up window with the options to update or uninstall the bundle. -3. Click the `Uninstall` button. -4. An initial check is made to verify that components are not in use outside of the bundle. A pop-up window will list the components with external references that must be removed manually and then the uninstall process may be resumed^. +1. Log in to your App Builder instance and select `Hub` from the left navigation menu to enter your Local Hub. +2. Click the `Installed` button to open a pop-up window with the available options. +3. Click `Uninstall`. +4. An initial check is done to verify that components are not in use outside of the bundle. A pop-up window will list the components with external references that must be cleared manually, and then the uninstall process may resume. 5. When the `Uninstall` is confirmed, a progress bar shows the following removal process: - Bundle resources are deleted from the Entando App Engine - Components included in the bundle are removed from the Entando App Engine - - Plugins are unlinked + - Microservices are unlinked 6. To remove the bundle from the Local Hub catalog, click the `Undeploy` button. -^ When unistalling a PBC or any component with **multiple bundles**, it is important to remove the bundles in the reverse order of installation because of dependencies. +::: tip Uninstall Order +When unistalling a PBC or a Bundle Group with multiple bundles, it is important to remove the bundles in the reverse order of installation due to dependencies. +::: ## Troubleshooting If an error occurs during the uninstall process, check out the [Troubleshooting guide](./troubleshooting-guide.md) or the [Entando Forum](https://forum.entando.com).