diff --git a/vuepress/docs/next/docs/curate/ecr-bundle-details.md b/vuepress/docs/next/docs/curate/ecr-bundle-details.md index c9f270ae2c..306f80680a 100644 --- a/vuepress/docs/next/docs/curate/ecr-bundle-details.md +++ b/vuepress/docs/next/docs/curate/ecr-bundle-details.md @@ -4,7 +4,6 @@ sidebarDepth: 2 # Bundle and Component Descriptors -## Overview The Entando Component Manager reads the `descriptor.yaml` file from the root of the bundle package and uses it to install any components and resources included in the bundle. The different component types are shown below: @@ -42,58 +41,59 @@ The bundle descriptor YAML file aggregates all included components and has the s # Optional. Use if the component requires deployment plugins: - - folder/you/want/my_plugin_descriptor.yaml + - folder/you/want/your_plugin_descriptor.yaml - folder/you/want/another_plugin_descriptor.yaml # To create Widgets, add references to the descriptor files widgets: - - widgets/my_widget_descriptor.yaml + - widgets/your_widget_descriptor.yaml - widgets/another_widget_descriptor.yaml # To create Fragments, add references to the descriptor files fragments: - - fragments/my_fragment.yaml + - fragments/your_fragment.yaml # To create Page Templates, add references to the descriptor files pageModels: - - pageModels/my_page_model_descriptor.yaml + - pageModels/your_page_model_descriptor.yaml - pageModels/another_page_model_descriptor.yaml # To create and publish Pages, add references to the descriptor files pages: - - page/my_page_descriptor.yaml + - page/your_page_descriptor.yaml - page/another_page_descriptor.yaml - # To create a CMS Asset, add a reference to the descriptor file in the same location as the image or file you want to upload + # To create a CMS Asset, add a reference to the descriptor file in the same location + # as the image or file you want to upload assets: - - assets/my-asset/my_asset_descriptor.yaml - - assets/my-asset/my_image.jpg + - assets/your-asset/your_asset_descriptor.yaml + - assets/your-asset/your_image.jpg # To create Content Types, add references to the descriptor files contentTypes: - - contentTypes/my_content_type_descriptor.yaml + - contentTypes/your_content_type_descriptor.yaml # To create Content Templates, add references to the descriptor files contentModels: - - contentModels/my_content_model_descriptor.yaml + - contentModels/your_content_model_descriptor.yaml - contentModels/another_content_model_descriptor.yaml # To create and publish Contents, add references to the descriptor files contents: - - contents/my_content_descriptor.yaml + - contents/your_content_descriptor.yaml - contents/another_content_descriptor.yaml # To create Categories, add references to the descriptor files categories: - - categories/my_categories.yaml + - categories/your_categories.yaml # To create Groups, add references to the descriptor files groups: - - groups/my_groups.yaml + - groups/your_groups.yaml # To create Labels, add references to the descriptor files labels: - - labels/my_labels.yaml + - labels/your_labels.yaml # To enable Languages, add references to the descriptor files languages: @@ -105,10 +105,22 @@ Here is an example of a plugin descriptor: **Plugin descriptor.yaml** - image: "entando/my-image:1.0.0" # The Docker image used to create the plugin - deploymentBaseName: "myplugin" # The base name to assign to pods that have to be created in Kubernetes - dbms: "postgresql" # The DBMS the plugin will use - roles: # The roles the plugin will expose in Keycloak + + # Descriptor version field added in v3 and later. + # To take advantage of the environment variables below, v4 will need to be specified. + descriptorVersion: "v4" + + # The Docker image used to create the plugin + image: "entando/your-image:1.0.0" + + # The base name to assign to pods that have to be created in Kubernetes + deploymentBaseName: "yourplugin" + + # The DBMS the plugin will use + dbms: "postgresql" + + # The roles the plugin will expose in Keycloak + roles: - "task-list" - "task-get" - "connection-list" @@ -116,17 +128,32 @@ Here is an example of a plugin descriptor: - "connection-create" - "connection-delete" - "connection-edit" - healthCheckPath: "/actuator/health" # The health check path that Kubernetes will use to check the status of the plugin deployment - ingressPath: "/myhostname.io/entando-plugin" # the ingress path to assign to the plugin deployment - permissions: # a list of Keycloak clientIds / roles to bind to one another + + # The health check path that Kubernetes will use to check the status + # of the plugin deployment + healthCheckPath: "/actuator/health" + + # The ingress path to assign to the plugin deployment + ingressPath: "/your-plugin-path" + + # A list of Keycloak clientIds/roles to bind to one another + permissions: - clientId: realm-management role: manage-users - clientId: realm-management role: view-users - environmentVariables: # a set of environment variables that can be set inline or reference secrets in the namespace - - name: MY_SIMPLE_VAR - value: mySimpleValue - + + # A set of environment variables that can be set inline or + # referenced as Secrets in the namespace. Supported as of descriptorVersion v4. + environmentVariables: + - name: SIMPLE_VAR # directly injects the value + value: yourSimpleValue + - name: SECRET_VAR # leverages a secret value + valueFrom: + secretKeyRef: + name: YOUR-BUNDLE-ID-your-secret + key: yourSecretKey + ::: tip Entando uses the `healthCheckPath` to monitor the health of the plugin. 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). ::: @@ -135,19 +162,6 @@ Here is an example of a plugin descriptor: See the [Plugin Environment Variables](../../tutorials/devops/plugin-environment-variables.md) tutorial to setup environment variables, either inline or based on Kubernetes Secrets. ::: -### Kubernetes Pod Names - -Each plugin is deployed into Kubernetes using composite names. The first string is created by reading the descriptor file. The second string is appended autonomously by Kubernetes and 31 characters long. Each Kubernetes pod name length must not exceed 63 characters or the deployment will fail. - -**DeploymentBaseName** - -Previously, the first segment of the pod name was generated by concatenating and manipulating the `image` field value. However, this approach could result in a pod name longer than 63 characters. -To solve this problem, another (optional) property is available: `deploymentBaseName`, which accepts a string of up to 32 characters. If present, its value will be used as the first part of the pod name instead of the variant of the `image` value. - -If the `deploymentBaseName` property is not present in the previous descriptor example, a possible pod name is `entando-my-image-1-0-0-server-deployment-6f86f459wj9k`. If the `deploymentBaseName` property is present, a possible pod name is `myplugin-server-deployment-6f86f459wj9k`. - -If you are using the `deploymentBaseName` property and want to install more versions of the same plugin at the same time, you need to specify different values for `deploymentBaseName` (perhaps including the plugin version). - ### Permissions The `permissions` property specifies a list of coupled `clientIds` and roles that will be bound in Keycloak. To find them, open the Keycloak console and navigate to `clients` → `awesomeplugin-server` → `Service Account Roles`. @@ -170,7 +184,7 @@ Here is an example of a Widget descriptor: # Optional. The Custom UI customUi: >- -

My custom Widget UI

+

Your Custom Widget UI

# Optional. The ConfigUI configUi: @@ -184,11 +198,11 @@ Here is an example of a Fragment descriptor: **Fragment descriptor.yaml** - code: my_fragment # The unique ID + code: your_fragment # The unique ID # Optional. The Fragment content guiCode: >- - "
Here the content
" + "
Here is the content
" # Optional. A path to a FreeMarker file containing the Fragment content guiCodePath: fragment.ftl @@ -217,7 +231,7 @@ Here is an example of a Page Template descriptor: 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: your-widget # the Widget code to apply when using the button "apply default widgets" in the page configuration UI # A simplified way to define a Frame - pos: 1 @@ -255,7 +269,7 @@ Groups in a page descriptor are configured by `ownerGroup` and `joinGroups`. The code: dashboard parentCode: homepage titles: - en: My dashboard + en: your dashboard it: La mia Dashboard pageModel: dashboard ownerGroup: free @@ -301,7 +315,7 @@ This descriptor contains the metadata required for uploading and updating a CMS **Asset descriptor.yaml** - correlationCode: 'my-reference-code' + correlationCode: 'your-reference-code' type: image # This file should be placed in the same folder as the descriptor.yaml name: 113f4437cac3b3f3d4db7229f12287a4_d3.png @@ -453,21 +467,21 @@ Groups in a content descriptor are configured by the owner group `mainGroup` and elements: - code: links value: - symbolicDestination: '#!U;http://www.mysite.com/!#' + symbolicDestination: '#!U;http://www.yoursite.com/!#' destType: 1 - urlDest: 'http://www.mysite.com/' + urlDest: 'http://www.yoursite.com/' pageDest: null contentDest: null resourceDest: null values: - en: mio sito + en: vostro sito - code: links value: - symbolicDestination: '#!U;http://www.mysite.com/!#' + symbolicDestination: '#!U;http://www.yoursite.com/!#' destType: 1 - urlDest: 'http://www.mysite.com/' + urlDest: 'http://www.yoursite.com/' values: - en: mio sito 2 + en: vostro sito 2 - code: attaches elements: - code: attaches @@ -495,18 +509,18 @@ This descriptor contains a list of Groups: **Group descriptor.yaml** - - code: my_group # Identifies the Group - name: "My group" # The name of the Group + - code: your_group # Identifies the Group + name: "Your group" # The name of the Group ## Labels This descriptor contains a list of Labels: **Label descriptor.yaml** - - key: MY-FIRST-LABEL # Identifies the Label + - key: YOUR-FIRST-LABEL # Identifies the Label titles: # The titles on the Label - it: Mio Titolo # The title in Italian - en: My Title # The title in English + it: Vostro Titolo # The title in Italian + en: Your Title # The title in English ## Languages This descriptor contains a list of Languages to enable during the installation process: @@ -535,7 +549,7 @@ In order to upload static files, you will need to create a folder called `resour Using the structure above, the resultant files in the Entando architecture will be: - yourbundleid/ + your-bundle-id/ ├ css/ │ └ styles.css ├ js/ @@ -547,11 +561,11 @@ Using the structure above, the resultant files in the Entando architecture will > **Important** > -> The `code` property `yourbundleid` is inside `descriptor.yaml`. +> The `code` property `your-bundle-id` is inside `descriptor.yaml`. To use static files in a Widget or Page Template, use the FTL tag `<@wp.resourceURL />`: - - - - + + + + diff --git a/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md b/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md index 4dcde6d51c..417ffbff41 100644 --- a/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md +++ b/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md @@ -70,10 +70,9 @@ ent jhipster --blueprints entando - If no database is selected you'll be building a stateless microservice, which is a valid choice, but the rest of this tutorial won't work. - `Which *production* database would you like to use?` (PostgreSQL or MySQL) - `Which *development* database would you like to use?` (H2 with disk-based persistence) - - `Which cache do you want to use? (Spring cache abstraction)` (Caffeine (local cache, for a single node)) + - `Do you want to use the Spring cache abstraction?` (Yes, with the Caffeine implementation (local cache, for a single node)) - `Do you want to use Hibernate 2nd level cache?` (Yes) - `Which other technologies would you like to use?` (**Don't select any other technologies**) - - `Which BE dependencies do you want to use?` (**Dependencies maintained by Entando (entando/entando-bundle-bom)**) - `What name would you give to the bundle to share on an Entando Component Repository?` (Up to you) - `Which is the organization name to use when publishing the docker image?` (**Enter the name of the organization where you are going to push your Docker image. If you're using your personal Docker hub account enter your username.**) <-- this can be changed later as needed - `Would you like to generate micro frontends when creating entities?` (Always) diff --git a/vuepress/docs/next/tutorials/devops/plugin-environment-variables.md b/vuepress/docs/next/tutorials/devops/plugin-environment-variables.md index ca88a2d2f1..cd8a58135c 100644 --- a/vuepress/docs/next/tutorials/devops/plugin-environment-variables.md +++ b/vuepress/docs/next/tutorials/devops/plugin-environment-variables.md @@ -46,7 +46,7 @@ environmentVariables: name: YOUR-BUNDLE-ID-my-secret key: mySecretKey ``` -4. [Build and deploy](../create/pb/publish-project-bundle.html) the updated bundle. +4. [Build and deploy](../create/pb/publish-project-bundle.md) the updated bundle. ## Verify the Environment Variables diff --git a/vuepress/docs/next/tutorials/solution/entando-hub.md b/vuepress/docs/next/tutorials/solution/entando-hub.md index 75b3789ef9..d03feb28ef 100644 --- a/vuepress/docs/next/tutorials/solution/entando-hub.md +++ b/vuepress/docs/next/tutorials/solution/entando-hub.md @@ -83,7 +83,7 @@ The key entities in the Entando Hub are: - `Bundle Group`: A Bundle Group is a group of one or more Entando Bundles. - `Bundle Group Version`: A Bundle Group can have one or more versions, each with a particular status. -- `Bundle`: A Bundle is the deployment unit within an Entando Application. A Bundle can contain one or multiple components such as micro frontends, microservices, or any of the [component types](../../docs/curate/ecr-bundle-details.md#overview) available in Entando. +- `Bundle`: A Bundle is the deployment unit within an Entando Application. A Bundle can contain one or multiple components such as micro frontends, microservices, or any of the [component types](../../docs/curate/ecr-bundle-details.md) available in Entando. - `Category`: Each Bundle Group belongs to a specific category. The initial possible categories are Solution Template, Packaged Business Capability (PBC), or Component Collection. An admin of an Entando Hub can refine the available categories as desired. - `Organization`: Bundle Groups belong to a single organization. Authors and managers can only update Bundle Groups for their own organization. - `User`: User identity is managed within Keycloak, where users are granted roles within the Hub. Users must be assigned to a specific organization.