diff --git a/vuepress/docs/next/docs/create/blueprint-features.md b/vuepress/docs/next/docs/create/blueprint-features.md index ee63c11506..6d151adca1 100644 --- a/vuepress/docs/next/docs/create/blueprint-features.md +++ b/vuepress/docs/next/docs/create/blueprint-features.md @@ -3,7 +3,7 @@ sidebarDepth: 2 --- # Entando Blueprint Features -The Entando Blueprint leverages JHipster technology to quickly and easily create components for an Entando Application, including a Spring Boot microservice and corresponding micro frontends. The user specifies application parameters to autogenerate the project files via Embedded JavaScript (EJS), a templating language that provides powerful constructs for large-scale file generation. The following sections examine the features of the Entando Blueprint. +The Entando Blueprint leverages JHipster technology to quickly and easily create components for an Entando Application, including a Spring Boot microservice and React micro frontends. Through a series of questions, the user specifies parameters to autogenerate the project files via Embedded JavaScript (EJS), a templating language that provides powerful constructs for large-scale file generation. The following examines the details of the Entando Blueprint. [Follow the Entando Blueprint tutorial](../../tutorials/create/ms/generate-microservices-and-micro-frontends.md). @@ -22,7 +22,7 @@ The Entando Blueprint leverages JHipster technology to quickly and easily create * Keycloak integration ## Preconfigured Micro Frontends -The creation of an entity using the Entando Blueprint generates the following preconfigured micro frontends. These are discussed in detail below. +The creation of an entity using the Entando Blueprint generates the following preconfigured micro frontends. Additional specifications follow. * [Authentication](#authentication) * [Custom Events](#custom-events) * [Tests and Mocks](#tests-and-mocks) @@ -37,14 +37,14 @@ The creation of an entity using the Entando Blueprint generates the following pr **What the micro frontends have in common:** -* Each micro frontend contains a README file to assist with its setup. -* All generated micro frontends are web components created using the custom elements +* Each micro frontend (MFE) contains a README file to assist with its setup. +* All generated micro frontends are web components created with the custom elements API. -* Each micro frontend is displayed using the custom element tag, e.g.: +* Each MFE is displayed using the custom element tag, e.g.: - The details widget file `microfrontends/conference-details/public/index.html` contains `conference-details id="1" override-edit-handler hide-edit-button />`. - The element `` is defined as a component entry in `microfrontends/conference-details/src/custom-elements/ConferenceDetailsElement.js`. -For more information about web components, custom elements and micro frontends, refer to [Create a React Micro Frontend](../../tutorials/create/mfe/react.md). +For more information about web components, custom elements and MFEs, refer to [Create a React Micro Frontend](../../tutorials/create/mfe/react.md). ### Authentication @@ -66,21 +66,21 @@ For more information on Keycloak and authentication with Entando, refer to the [ ### Custom Events - All MFEs rely on custom events for communication. Consequently, each MFE is able to create or remove custom events and event listeners. -- An event listener should be created in the custom element’s `disconnectedCallback()` function, and only when the element is no longer needed. +- An event listener should be added in the custom element’s `disconnectedCallback()` function when it is no longer needed. - To add an event to the listener list, add the event type to the `INPUT_EVENT_TYPES` object at -`microfrontends/conference-details/src/custom-elements/widgetEventTypes.js`. To remove an event listener, simply remove the element from the list. +`microfrontends/conference-details/src/custom-elements/widgetEventTypes.js`. To remove an event listener, remove the type from the list as well. Refer to [Communicate Between Micro Frontends](../../tutorials/create/mfe/communication.md) for more information about custom events and MFE communication. ### Tests and Mocks -- Tests have been written for each preconfigured MFE using `react-testing-library`. These can be updated via a preferred developer tool. -- The tests and mocks for each micro frontend are located in its `/src/components/` directory. +- Tests have been written for each preconfigured MFE using `react-testing-library`. These can be updated via your preferred developer tool. +- The tests and mocks for each micro frontend are located in their `/src/components/` directories. ### PropTypes - PropTypes for data used across several components are available to view or modify at `microfrontends/conference-details/src/components/`. -- These are shared resources and can be imported into components to avoid the repetition of definitions, e.g.: +- These are shared resources and can be imported into components to avoid repeated definitions, e.g.: ``` shell import React from 'react'; import conferenceType from 'components/__types__/conference'; diff --git a/vuepress/docs/next/docs/create/component-gen-customize.md b/vuepress/docs/next/docs/create/component-gen-customize.md index 08bb53813e..d80825df53 100644 --- a/vuepress/docs/next/docs/create/component-gen-customize.md +++ b/vuepress/docs/next/docs/create/component-gen-customize.md @@ -1,7 +1,10 @@ +--- +sidebarDepth: 2 +--- # Customizing the Entando Component Generator -The Entando Component Generator is an instance of a JHipster blueprint that can be extended to match your team's needs and requirements. If you're interested in extending the blueprint or creating your own blueprint, contact us on the [Entando Forum](https://forum.entando.com/) or [Community Slack](https://join.slack.com/t/entandocommunity/shared_invite/zt-g609owdv-2K~YRh8zrI6lqlWo4aFWUw) and we'll help you get started. +The Entando Component Generator is an instance of a JHipster blueprint that can be extended to match your team's needs and requirements. If you're interested in extending the blueprint or creating your own, contact us on the [Entando Forum](https://forum.entando.com/) or [Community Slack](https://join.slack.com/t/entandocommunity/shared_invite/zt-g609owdv-2K~YRh8zrI6lqlWo4aFWUw) and we'll help you get started. This is the source for the [Entando Blueprint](https://github.com/entando/generator-jhipster-entando). -To learn more about creating blueprints and to see other blueprints available from JHipster checkout the [blueprint documentation](https://www.jhipster.tech/modules/creating-a-blueprint/) or visit [JHipster](https://www.jhipster.tech) for an overview. +To learn more about creating blueprints and to see other blueprints available from JHipster, checkout the [blueprint documentation](https://www.jhipster.tech/modules/creating-a-blueprint/) or visit [JHipster](https://www.jhipster.tech) for an overview. diff --git a/vuepress/docs/next/docs/create/component-gen-overview.md b/vuepress/docs/next/docs/create/component-gen-overview.md index 38756f355f..2abd6932e1 100644 --- a/vuepress/docs/next/docs/create/component-gen-overview.md +++ b/vuepress/docs/next/docs/create/component-gen-overview.md @@ -3,46 +3,46 @@ sidebarDepth: 2 --- # Entando Component Generator +The Entando Component Generator (ECG) is a tool that quickly generates project files for the modular components that make up a composable application. -The Entando Component Generator, powered by JHipster, is a tool that quickly generates Entando components to extend an Entando Application. - -The Component Generator leverages the [JHipster blueprint](https://www.jhipster.tech/modules/creating-a-blueprint/) to provide powerful templating and standard generation patterns. +The ECG leverages the [JHipster blueprint](https://www.jhipster.tech/modules/creating-a-blueprint/), providing powerful templating and standardized generation patterns. ## Objectives -The Component Generator has two main objectives, acceleration and standardization, which are examined below in greater detail. +The Component Generator has two main objectives, to standardize components and accelerate their development as described further below. ### Accelerate Development -- Begin with running software: By automating the creation of microservices and micro frontends, the developer is able to bypass the manual steps that would have been required to build the default configuration of an Entando project. -- Customize as desired: The generated code is ready to be further developed and modified to enable features and capabilities. -- Avoid a learning curve: The Entando Blueprint uses standard tools, technologies, and patterns that can be consumed by developers who are not familiar with the underlying technology. +- Begin by running the software: By automating the creation of microservices and micro frontends, the developer is able to bypass the manual steps that would have been required to build the default configuration of an Entando project. +- Customize as desired: The generated code is ready to be further modified and tailored to fit your unique needs. +- Avoid a steep learning curve: The Entando Blueprint uses standard tools, technologies, and patterns that can be consumed by any developer, especially those who are not familiar with the underlying system. ### Standardize Technology -- Guarantee technology compliance: The Component Generator encodes business standards for networking, monitoring, build tools, and distribution into the Entando Blueprint to ensure that business requirements are satisfied. -- Guarantee internal compliance: The Entando Blueprint provides parameters to ensure the code complies with standards and practices of your organization including formatting, testing tools, static analysis tools, and package structures. +- Guarantee technology compliance: The ECG encodes business standards for networking, monitoring, build tools, and distribution into the Entando Blueprint to ensure that business requirements are satisfied. +- Guarantee internal compliance: The Entando Blueprint provides parameters to ensure the code complies with the standards and practices of your organization, including formatting, testing tools, static analysis tools, and package structures. - Jumpstart 3rd party adoption: Teams can quickly recognize and adopt code from system integrators and other third parties because these patterns and standards are encoded into the default application. -## Generated Component Flow +## Component Generation Flow The following provides an overview of the component generation process. To view the code and learn how to use the Entando Blueprint, refer to the [Entando Component Generator Tutorial](../../tutorials/create/ms/generate-microservices-and-micro-frontends.md). 1. Create components - - The Component Generator creates a Spring Boot microservice and, optionally, React micro frontends for entities that you add to your project. - - The microservice and (optional) micro frontends are out-of-the-box runnable and preconfigured to connect to the [Entando Identity Management System](../consume/identity-management.md). - - JHipster offers interactive updates and merges to ensure the Entando Blueprint conforms to the current software revision. Developers can perform their own modifications to enhance the generated code or add new functionality via JHipster. + - The ECG creates a Spring Boot microservice and optionally, React micro frontends for entities that you add to your project. + - The microservice and (optional) micro frontends are runnable out of the box, preconfigured to connect to the [Entando Identity Management System](../consume/identity-management.md). + - JHipster offers interactive updates and merges to ensure the Blueprint conforms to the current software revision. Developers can perform their own modifications to enhance the generated code or add new functionality via JHipster. - The microservice includes Liquibase and integrated data mocking to offer data generation in API calls. 2. Define the bundle and deploy assets - - The Entando Blueprint generates code compatible with the docker-based bundle project structure introduced in Entando 7.1. The bundle project includes a microservice and entity-level microfrontends as well as other components added manually to the project. - - The bundle project is packed into a Docker image to provide the manifest for the components contained in the project. + - The Entando Blueprint generates code compatible with the docker-based bundle project structure. This includes a microservice and entity-level micro frontends, as well as any other components manually added to the project. + - The project is packaged into a Docker image to provide the manifest for the component parts. - The Spring Boot microservice is packed into its own Docker image. 3. Deploy bundles to the [Local Hub](../compose/local-hub-overview.md) - - Once the Docker images are pushed to a registry, the bundle can be deployed to the Local Hub in an Entando Application. - - Production bundles are installed to the Local Hub as a default of the Entando Component Manager. This is determined by the tag types and for more information, see the [Entando Component Manager features](../compose/ecm-overview.md#key-features). - - The bundle project can be versioned and updated at any time. + - Once the Docker images are pushed to a registry, the bundle can be deployed to the Local Hub in the App Builder. + - Production bundles are installed to the Local Hub as a default of the Entando Component Manager. Development versions can be installed to the Local Hub via tag types, and for more information, see the [Entando Component Manager features](../compose/ecm-overview.md#key-features). + - A bundle project can be versioned and updated for improvements at any time. -4. Install in Entando Apps - - Once the bundle is deployed to the Local Hub, it can be installed in the Entando Application. +4. Install in an application + - Once the bundle is deployed to the Local Hub, it can be installed in any Entando Application. + - The bundle can be shared in an Enterprise Hub, if one was installed, to be used in other applications. diff --git a/vuepress/docs/next/docs/create/component-gen-tech.md b/vuepress/docs/next/docs/create/component-gen-tech.md index f8959abef1..cca3cd4c30 100644 --- a/vuepress/docs/next/docs/create/component-gen-tech.md +++ b/vuepress/docs/next/docs/create/component-gen-tech.md @@ -1,26 +1,26 @@ # Component Generation Technologies -When generating a microservice or micro frontend using the Entando Component Generator, there are a number of technical choices that need to be made: +When generating a microservice or micro frontend using the Entando Component Generator (ECG), there are a number of technical choices that need to be considered: * Microservice code - * If you're considering microservices that are not based on Java, here are the [specifications of an Entando microservice](../curate/bundle-details.md#microservices-specifications), including information on the runtime contract required to use them. + * If you're considering microservices that are not Java-based, here are the [specifications of an Entando microservice](../curate/bundle-details.md#microservices-specifications), including information on the runtime contract required to use them. * For a JavaScript example, see the Node.js microservice in the [API claim tutorial](../../tutorials/create/ms/add-api-claim.md). * Database type - * Entando recommends standardizing your choice of database to simplify operational maintenance, but you do have the ability to use different databases for different microservices. + * Entando recommends standardizing your database choice to simplify operational maintenance, but you still have the option to use different databases for different microservices. * Supported choices are none, embedded, MySQL, and Postgres. Enterprise customers can choose Oracle but should contact Entando Support for details. * Development databases - * You can choose to utilize a full RDBMS or developers can utilize lightweight in-memory or on-disk databases with H2. + * You can choose to utilize a full RDBMS, lightweight in-memory, or on-disk databases with H2. * Caching implementation - * When generating a microservice, you will be presented with the types of cache to inject into the services. It is recommended that the type be uniform for all microservices in your application, but it can be customized on a per-service basis if desired. + * When generating a microservice, you will be presented with the types of cache to inject into the services. It is recommended that the type be uniform for all microservices in your application, but it can be customized on a per-service basis, if desired. * Build system * Determines the Java build tool to use when building your services * Supports Maven or Gradle * Other technologies - * Users of the Component Generator can also decide to use other technologies from JHipster or the JHipster marketplace. + * Users of the ECG can also decide to use other technologies from JHipster or the JHipster marketplace. * There are many powerful technologies in the marketplace but it is up to the developer to integrate the chosen technology into their Entando Application. Entando doesn't provide direct support for marketplace tech choices. * Micro frontends * Optionally, users can choose to generate micro frontends for entities generated via the blueprint. - * The Entando Component Generator only provides micro frontends in React from the generation flow but developers can create and bundle micro frontends using other technologies as well. + * The Entando Component Generator only provides micro frontends in React from the generation flow but developers can create and bundle frontend components using other technologies as well. ## Next Steps diff --git a/vuepress/docs/next/docs/create/how-microservices-connect-to-apps.md b/vuepress/docs/next/docs/create/how-microservices-connect-to-apps.md index 29fbccf189..41cb635cf1 100644 --- a/vuepress/docs/next/docs/create/how-microservices-connect-to-apps.md +++ b/vuepress/docs/next/docs/create/how-microservices-connect-to-apps.md @@ -1,45 +1,48 @@ -# How Microservices get Connected to Entando Apps +--- +sidebarDepth: 2 +--- +# How Microservices Connect to Entando Apps -In this document we will describe some of the assumptions and details related to the process of connecting a microservice part of a bundle to an Entando App. +In this document, the assumptions and details related to the process of connecting a microservice to an Entando App is examined. -In order to fully understand the concepts explained in this piece of the documentation, please make sure you have familiarity with these concepts: +In order to fully understand the process, please familiarize yourself with these support documents: 1. [Entando custom resources](../reference/custom-resources.md) 2. [Entando ingresses](../getting-started/concepts-overview.md#entando-ingresses) -## How a Microservice from a Bundle gets Deployed with the ECR? +## How a Microservice from a Bundle Gets Deployed -When a bundle containing a microservice is installed using the ECR, behind the scenes some actions take place. +When a bundle containing a microservice is installed in the Local Hub, some behind the scenes actions take place. -1. To begin, an [EntandoPlugin custom resource](https://github.com/entando-k8s/entando-k8s-custom-model/blob/master/src/main/resources/crd/entandoplugins.entando.org.crd.yaml) is generated starting from the PluginDescriptor. Some fields will be automatically generated from the provided image. -- From the `image` field in the PluginDescriptor, we will extract the `organization`, `name` and `version` of the image. -- `organization`, `name` and `version` are then converted to valid characters and composed to form the plugin name (`metadata.name`), the labels (`metadata.labels`) and the ingressPath (`spec.ingressPath`) of the custom resource. +1. To begin, [EntandoPlugin custom resources](https://github.com/entando-k8s/entando-k8s-custom-model/blob/master/src/main/resources/crd/entandoplugins.entando.org.crd.yaml) are generated starting with the PluginDescriptor. Some fields will be automatically generated from the provided image. + * From the `image` field in the PluginDescriptor, the `organization`, `name` and `version` of the image will be extracted. + * `organization`, `name` and `version` are then converted to valid characters and composed to form the plugin name (`metadata.name`), the labels (`metadata.labels`) and the ingressPath (`spec.ingressPath`) of the custom resource. -**NOTE**: Two PluginDescriptors having images with the same organization, name and version will generate a custom resource with the same `metadata.name` and `spec.ingressPath`. + **NOTE**: Two PluginDescriptors having images with the same organization, name and version will generate a custom resource with the same `metadata.name` and `spec.ingressPath`. -2. Next, a check for a microservice with the same name is performed to verify if a new deployment is required for the microservice. -3. If a microservice with the same name is not available in the namespace where the Entando App has been deployed, a new EntandoPlugin custom resource is created and deployed in the namespace using the details defined in the bundle. +2. Next, a check for a microservice with the same name is performed to verify if a new deployment is required. +3. If a microservice with the same name does not exist in the namespace where the EntandoApp has been deployed, a new EntandoPlugin custom resource is created and deployed in that namespace, using the details defined in the bundle. 4. At the same time, an EntandoAppPluginLink custom resource is deployed in the namespace in order to expose the microservice ingress path on the EntandoApp ingress. -5. If both the EntandoPlugin custom resource and the EntandoAppPluginLink are deployed correctly, the APIs of the microservice will be available from the same domain of the EntandoApp, making it possible reach those APIs from the EntandoApp using relative urls. +5. If both the EntandoPlugin and the EntandoAppPluginLink custom resources are deployed correctly, the APIs of the microservice will be available from the same domain of the EntandoApp, making it possible to reach those APIs from the EntandoApp using relative urls. -This is the standard flow when no other micorservice with a given name is already available in the EntandoApp namespace. +This is the standard flow when no other micorservice with the same name is already present in the EntandoApp namespace. If there is an existing microservice with the same name as the one generated from the PluginDescriptor, the Local Hub will connect the EntandoApp to -the existing microservice by generating and deploying the required EntandoAppPluginLink per step 3 above. +the existing microservice by generating and deploying the required EntandoAppPluginLink per step three above. This way, plugins can be reused by many applications at the same time. ## Other Options -The naming convention recommendations above are accurate for creating bundles and for self contained applications where the Entando operator is managing the lifecycle of your microservices. If you have a substantial API infrastructure or you intend to deploy a large number of versioned microservices you can also utilize Entando with API management infrastructure like API gateways. If you are using an API gateway or other API abstraction layer you will need to manually manage the ingress for your micro frontends in your application to point to the API gateway deployment. +The naming convention recommended above are accurate for creating bundles and for self contained applications where the Entando Operator is managing the lifecycle of your microservices. If you have a substantial API infrastructure or intend to deploy a large number of versioned microservices, you can also utilize an API management infrastructure like API gateways. If you use an API gateway or other API abstraction layer, you will need to manually manage the ingress for the micro frontends in your application to point to the API gateway deployment. -In cases where conflicts occur bundles can easily be renamed by updating metdata. +In cases where conflicts occur, bundles can easily be renamed by updating metdata. -## Kubernetes naming conventions +## Kubernetes Naming Conventions -Here some rules about naming conventions extracted from the [Kubernetes documentation on object names and ids](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/) +Here are a few recommendations about naming conventions extracted from the [Kubernetes documentation on object names and ids](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/). -> Most resource types require a name that can be used as a DNS subdomain name as defined in RFC 1123. This means the name must: -> - contain no more than 253 characters -> - contain only lowercase alphanumeric characters, '-' or '.' -> - start with an alphanumeric character -> - end with an alphanumeric character +Most resource types require a name that can be used as a DNS subdomain name as defined in RFC 1123. This means the name must: + - contain no more than 253 characters + - contain only lowercase alphanumeric characters, '-' or '.' + - start with an alphanumeric character + - end with an alphanumeric character diff --git a/vuepress/docs/v7.3/docs/create/blueprint-features.md b/vuepress/docs/v7.3/docs/create/blueprint-features.md index ee63c11506..6d151adca1 100644 --- a/vuepress/docs/v7.3/docs/create/blueprint-features.md +++ b/vuepress/docs/v7.3/docs/create/blueprint-features.md @@ -3,7 +3,7 @@ sidebarDepth: 2 --- # Entando Blueprint Features -The Entando Blueprint leverages JHipster technology to quickly and easily create components for an Entando Application, including a Spring Boot microservice and corresponding micro frontends. The user specifies application parameters to autogenerate the project files via Embedded JavaScript (EJS), a templating language that provides powerful constructs for large-scale file generation. The following sections examine the features of the Entando Blueprint. +The Entando Blueprint leverages JHipster technology to quickly and easily create components for an Entando Application, including a Spring Boot microservice and React micro frontends. Through a series of questions, the user specifies parameters to autogenerate the project files via Embedded JavaScript (EJS), a templating language that provides powerful constructs for large-scale file generation. The following examines the details of the Entando Blueprint. [Follow the Entando Blueprint tutorial](../../tutorials/create/ms/generate-microservices-and-micro-frontends.md). @@ -22,7 +22,7 @@ The Entando Blueprint leverages JHipster technology to quickly and easily create * Keycloak integration ## Preconfigured Micro Frontends -The creation of an entity using the Entando Blueprint generates the following preconfigured micro frontends. These are discussed in detail below. +The creation of an entity using the Entando Blueprint generates the following preconfigured micro frontends. Additional specifications follow. * [Authentication](#authentication) * [Custom Events](#custom-events) * [Tests and Mocks](#tests-and-mocks) @@ -37,14 +37,14 @@ The creation of an entity using the Entando Blueprint generates the following pr **What the micro frontends have in common:** -* Each micro frontend contains a README file to assist with its setup. -* All generated micro frontends are web components created using the custom elements +* Each micro frontend (MFE) contains a README file to assist with its setup. +* All generated micro frontends are web components created with the custom elements API. -* Each micro frontend is displayed using the custom element tag, e.g.: +* Each MFE is displayed using the custom element tag, e.g.: - The details widget file `microfrontends/conference-details/public/index.html` contains `conference-details id="1" override-edit-handler hide-edit-button />`. - The element `` is defined as a component entry in `microfrontends/conference-details/src/custom-elements/ConferenceDetailsElement.js`. -For more information about web components, custom elements and micro frontends, refer to [Create a React Micro Frontend](../../tutorials/create/mfe/react.md). +For more information about web components, custom elements and MFEs, refer to [Create a React Micro Frontend](../../tutorials/create/mfe/react.md). ### Authentication @@ -66,21 +66,21 @@ For more information on Keycloak and authentication with Entando, refer to the [ ### Custom Events - All MFEs rely on custom events for communication. Consequently, each MFE is able to create or remove custom events and event listeners. -- An event listener should be created in the custom element’s `disconnectedCallback()` function, and only when the element is no longer needed. +- An event listener should be added in the custom element’s `disconnectedCallback()` function when it is no longer needed. - To add an event to the listener list, add the event type to the `INPUT_EVENT_TYPES` object at -`microfrontends/conference-details/src/custom-elements/widgetEventTypes.js`. To remove an event listener, simply remove the element from the list. +`microfrontends/conference-details/src/custom-elements/widgetEventTypes.js`. To remove an event listener, remove the type from the list as well. Refer to [Communicate Between Micro Frontends](../../tutorials/create/mfe/communication.md) for more information about custom events and MFE communication. ### Tests and Mocks -- Tests have been written for each preconfigured MFE using `react-testing-library`. These can be updated via a preferred developer tool. -- The tests and mocks for each micro frontend are located in its `/src/components/` directory. +- Tests have been written for each preconfigured MFE using `react-testing-library`. These can be updated via your preferred developer tool. +- The tests and mocks for each micro frontend are located in their `/src/components/` directories. ### PropTypes - PropTypes for data used across several components are available to view or modify at `microfrontends/conference-details/src/components/`. -- These are shared resources and can be imported into components to avoid the repetition of definitions, e.g.: +- These are shared resources and can be imported into components to avoid repeated definitions, e.g.: ``` shell import React from 'react'; import conferenceType from 'components/__types__/conference'; diff --git a/vuepress/docs/v7.3/docs/create/component-gen-customize.md b/vuepress/docs/v7.3/docs/create/component-gen-customize.md index 08bb53813e..404bd21656 100644 --- a/vuepress/docs/v7.3/docs/create/component-gen-customize.md +++ b/vuepress/docs/v7.3/docs/create/component-gen-customize.md @@ -1,7 +1,11 @@ +--- +sidebarDepth: 2 +--- # Customizing the Entando Component Generator -The Entando Component Generator is an instance of a JHipster blueprint that can be extended to match your team's needs and requirements. If you're interested in extending the blueprint or creating your own blueprint, contact us on the [Entando Forum](https://forum.entando.com/) or [Community Slack](https://join.slack.com/t/entandocommunity/shared_invite/zt-g609owdv-2K~YRh8zrI6lqlWo4aFWUw) and we'll help you get started. +The Entando Component Generator is an instance of a JHipster blueprint that can be extended to match your team's needs and requirements. If you're interested in extending the blueprint or creating your own, contact us on the [Entando Forum](https://forum.entando.com/) or [Community Slack](https://join.slack.com/t/entandocommunity/shared_invite/zt-g609owdv-2K~YRh8zrI6lqlWo4aFWUw) and we'll help you get started. This is the source for the [Entando Blueprint](https://github.com/entando/generator-jhipster-entando). -To learn more about creating blueprints and to see other blueprints available from JHipster checkout the [blueprint documentation](https://www.jhipster.tech/modules/creating-a-blueprint/) or visit [JHipster](https://www.jhipster.tech) for an overview. +To learn more about creating blueprints and to see other blueprints available from JHipster, checkout the [blueprint documentation](https://www.jhipster.tech/modules/creating-a-blueprint/) or visit [JHipster](https://www.jhipster.tech) for an overview. + diff --git a/vuepress/docs/v7.3/docs/create/component-gen-overview.md b/vuepress/docs/v7.3/docs/create/component-gen-overview.md index 38756f355f..2abd6932e1 100644 --- a/vuepress/docs/v7.3/docs/create/component-gen-overview.md +++ b/vuepress/docs/v7.3/docs/create/component-gen-overview.md @@ -3,46 +3,46 @@ sidebarDepth: 2 --- # Entando Component Generator +The Entando Component Generator (ECG) is a tool that quickly generates project files for the modular components that make up a composable application. -The Entando Component Generator, powered by JHipster, is a tool that quickly generates Entando components to extend an Entando Application. - -The Component Generator leverages the [JHipster blueprint](https://www.jhipster.tech/modules/creating-a-blueprint/) to provide powerful templating and standard generation patterns. +The ECG leverages the [JHipster blueprint](https://www.jhipster.tech/modules/creating-a-blueprint/), providing powerful templating and standardized generation patterns. ## Objectives -The Component Generator has two main objectives, acceleration and standardization, which are examined below in greater detail. +The Component Generator has two main objectives, to standardize components and accelerate their development as described further below. ### Accelerate Development -- Begin with running software: By automating the creation of microservices and micro frontends, the developer is able to bypass the manual steps that would have been required to build the default configuration of an Entando project. -- Customize as desired: The generated code is ready to be further developed and modified to enable features and capabilities. -- Avoid a learning curve: The Entando Blueprint uses standard tools, technologies, and patterns that can be consumed by developers who are not familiar with the underlying technology. +- Begin by running the software: By automating the creation of microservices and micro frontends, the developer is able to bypass the manual steps that would have been required to build the default configuration of an Entando project. +- Customize as desired: The generated code is ready to be further modified and tailored to fit your unique needs. +- Avoid a steep learning curve: The Entando Blueprint uses standard tools, technologies, and patterns that can be consumed by any developer, especially those who are not familiar with the underlying system. ### Standardize Technology -- Guarantee technology compliance: The Component Generator encodes business standards for networking, monitoring, build tools, and distribution into the Entando Blueprint to ensure that business requirements are satisfied. -- Guarantee internal compliance: The Entando Blueprint provides parameters to ensure the code complies with standards and practices of your organization including formatting, testing tools, static analysis tools, and package structures. +- Guarantee technology compliance: The ECG encodes business standards for networking, monitoring, build tools, and distribution into the Entando Blueprint to ensure that business requirements are satisfied. +- Guarantee internal compliance: The Entando Blueprint provides parameters to ensure the code complies with the standards and practices of your organization, including formatting, testing tools, static analysis tools, and package structures. - Jumpstart 3rd party adoption: Teams can quickly recognize and adopt code from system integrators and other third parties because these patterns and standards are encoded into the default application. -## Generated Component Flow +## Component Generation Flow The following provides an overview of the component generation process. To view the code and learn how to use the Entando Blueprint, refer to the [Entando Component Generator Tutorial](../../tutorials/create/ms/generate-microservices-and-micro-frontends.md). 1. Create components - - The Component Generator creates a Spring Boot microservice and, optionally, React micro frontends for entities that you add to your project. - - The microservice and (optional) micro frontends are out-of-the-box runnable and preconfigured to connect to the [Entando Identity Management System](../consume/identity-management.md). - - JHipster offers interactive updates and merges to ensure the Entando Blueprint conforms to the current software revision. Developers can perform their own modifications to enhance the generated code or add new functionality via JHipster. + - The ECG creates a Spring Boot microservice and optionally, React micro frontends for entities that you add to your project. + - The microservice and (optional) micro frontends are runnable out of the box, preconfigured to connect to the [Entando Identity Management System](../consume/identity-management.md). + - JHipster offers interactive updates and merges to ensure the Blueprint conforms to the current software revision. Developers can perform their own modifications to enhance the generated code or add new functionality via JHipster. - The microservice includes Liquibase and integrated data mocking to offer data generation in API calls. 2. Define the bundle and deploy assets - - The Entando Blueprint generates code compatible with the docker-based bundle project structure introduced in Entando 7.1. The bundle project includes a microservice and entity-level microfrontends as well as other components added manually to the project. - - The bundle project is packed into a Docker image to provide the manifest for the components contained in the project. + - The Entando Blueprint generates code compatible with the docker-based bundle project structure. This includes a microservice and entity-level micro frontends, as well as any other components manually added to the project. + - The project is packaged into a Docker image to provide the manifest for the component parts. - The Spring Boot microservice is packed into its own Docker image. 3. Deploy bundles to the [Local Hub](../compose/local-hub-overview.md) - - Once the Docker images are pushed to a registry, the bundle can be deployed to the Local Hub in an Entando Application. - - Production bundles are installed to the Local Hub as a default of the Entando Component Manager. This is determined by the tag types and for more information, see the [Entando Component Manager features](../compose/ecm-overview.md#key-features). - - The bundle project can be versioned and updated at any time. + - Once the Docker images are pushed to a registry, the bundle can be deployed to the Local Hub in the App Builder. + - Production bundles are installed to the Local Hub as a default of the Entando Component Manager. Development versions can be installed to the Local Hub via tag types, and for more information, see the [Entando Component Manager features](../compose/ecm-overview.md#key-features). + - A bundle project can be versioned and updated for improvements at any time. -4. Install in Entando Apps - - Once the bundle is deployed to the Local Hub, it can be installed in the Entando Application. +4. Install in an application + - Once the bundle is deployed to the Local Hub, it can be installed in any Entando Application. + - The bundle can be shared in an Enterprise Hub, if one was installed, to be used in other applications. diff --git a/vuepress/docs/v7.3/docs/create/component-gen-tech.md b/vuepress/docs/v7.3/docs/create/component-gen-tech.md index f8959abef1..cca3cd4c30 100644 --- a/vuepress/docs/v7.3/docs/create/component-gen-tech.md +++ b/vuepress/docs/v7.3/docs/create/component-gen-tech.md @@ -1,26 +1,26 @@ # Component Generation Technologies -When generating a microservice or micro frontend using the Entando Component Generator, there are a number of technical choices that need to be made: +When generating a microservice or micro frontend using the Entando Component Generator (ECG), there are a number of technical choices that need to be considered: * Microservice code - * If you're considering microservices that are not based on Java, here are the [specifications of an Entando microservice](../curate/bundle-details.md#microservices-specifications), including information on the runtime contract required to use them. + * If you're considering microservices that are not Java-based, here are the [specifications of an Entando microservice](../curate/bundle-details.md#microservices-specifications), including information on the runtime contract required to use them. * For a JavaScript example, see the Node.js microservice in the [API claim tutorial](../../tutorials/create/ms/add-api-claim.md). * Database type - * Entando recommends standardizing your choice of database to simplify operational maintenance, but you do have the ability to use different databases for different microservices. + * Entando recommends standardizing your database choice to simplify operational maintenance, but you still have the option to use different databases for different microservices. * Supported choices are none, embedded, MySQL, and Postgres. Enterprise customers can choose Oracle but should contact Entando Support for details. * Development databases - * You can choose to utilize a full RDBMS or developers can utilize lightweight in-memory or on-disk databases with H2. + * You can choose to utilize a full RDBMS, lightweight in-memory, or on-disk databases with H2. * Caching implementation - * When generating a microservice, you will be presented with the types of cache to inject into the services. It is recommended that the type be uniform for all microservices in your application, but it can be customized on a per-service basis if desired. + * When generating a microservice, you will be presented with the types of cache to inject into the services. It is recommended that the type be uniform for all microservices in your application, but it can be customized on a per-service basis, if desired. * Build system * Determines the Java build tool to use when building your services * Supports Maven or Gradle * Other technologies - * Users of the Component Generator can also decide to use other technologies from JHipster or the JHipster marketplace. + * Users of the ECG can also decide to use other technologies from JHipster or the JHipster marketplace. * There are many powerful technologies in the marketplace but it is up to the developer to integrate the chosen technology into their Entando Application. Entando doesn't provide direct support for marketplace tech choices. * Micro frontends * Optionally, users can choose to generate micro frontends for entities generated via the blueprint. - * The Entando Component Generator only provides micro frontends in React from the generation flow but developers can create and bundle micro frontends using other technologies as well. + * The Entando Component Generator only provides micro frontends in React from the generation flow but developers can create and bundle frontend components using other technologies as well. ## Next Steps diff --git a/vuepress/docs/v7.3/docs/create/how-microservices-connect-to-apps.md b/vuepress/docs/v7.3/docs/create/how-microservices-connect-to-apps.md index 29fbccf189..41cb635cf1 100644 --- a/vuepress/docs/v7.3/docs/create/how-microservices-connect-to-apps.md +++ b/vuepress/docs/v7.3/docs/create/how-microservices-connect-to-apps.md @@ -1,45 +1,48 @@ -# How Microservices get Connected to Entando Apps +--- +sidebarDepth: 2 +--- +# How Microservices Connect to Entando Apps -In this document we will describe some of the assumptions and details related to the process of connecting a microservice part of a bundle to an Entando App. +In this document, the assumptions and details related to the process of connecting a microservice to an Entando App is examined. -In order to fully understand the concepts explained in this piece of the documentation, please make sure you have familiarity with these concepts: +In order to fully understand the process, please familiarize yourself with these support documents: 1. [Entando custom resources](../reference/custom-resources.md) 2. [Entando ingresses](../getting-started/concepts-overview.md#entando-ingresses) -## How a Microservice from a Bundle gets Deployed with the ECR? +## How a Microservice from a Bundle Gets Deployed -When a bundle containing a microservice is installed using the ECR, behind the scenes some actions take place. +When a bundle containing a microservice is installed in the Local Hub, some behind the scenes actions take place. -1. To begin, an [EntandoPlugin custom resource](https://github.com/entando-k8s/entando-k8s-custom-model/blob/master/src/main/resources/crd/entandoplugins.entando.org.crd.yaml) is generated starting from the PluginDescriptor. Some fields will be automatically generated from the provided image. -- From the `image` field in the PluginDescriptor, we will extract the `organization`, `name` and `version` of the image. -- `organization`, `name` and `version` are then converted to valid characters and composed to form the plugin name (`metadata.name`), the labels (`metadata.labels`) and the ingressPath (`spec.ingressPath`) of the custom resource. +1. To begin, [EntandoPlugin custom resources](https://github.com/entando-k8s/entando-k8s-custom-model/blob/master/src/main/resources/crd/entandoplugins.entando.org.crd.yaml) are generated starting with the PluginDescriptor. Some fields will be automatically generated from the provided image. + * From the `image` field in the PluginDescriptor, the `organization`, `name` and `version` of the image will be extracted. + * `organization`, `name` and `version` are then converted to valid characters and composed to form the plugin name (`metadata.name`), the labels (`metadata.labels`) and the ingressPath (`spec.ingressPath`) of the custom resource. -**NOTE**: Two PluginDescriptors having images with the same organization, name and version will generate a custom resource with the same `metadata.name` and `spec.ingressPath`. + **NOTE**: Two PluginDescriptors having images with the same organization, name and version will generate a custom resource with the same `metadata.name` and `spec.ingressPath`. -2. Next, a check for a microservice with the same name is performed to verify if a new deployment is required for the microservice. -3. If a microservice with the same name is not available in the namespace where the Entando App has been deployed, a new EntandoPlugin custom resource is created and deployed in the namespace using the details defined in the bundle. +2. Next, a check for a microservice with the same name is performed to verify if a new deployment is required. +3. If a microservice with the same name does not exist in the namespace where the EntandoApp has been deployed, a new EntandoPlugin custom resource is created and deployed in that namespace, using the details defined in the bundle. 4. At the same time, an EntandoAppPluginLink custom resource is deployed in the namespace in order to expose the microservice ingress path on the EntandoApp ingress. -5. If both the EntandoPlugin custom resource and the EntandoAppPluginLink are deployed correctly, the APIs of the microservice will be available from the same domain of the EntandoApp, making it possible reach those APIs from the EntandoApp using relative urls. +5. If both the EntandoPlugin and the EntandoAppPluginLink custom resources are deployed correctly, the APIs of the microservice will be available from the same domain of the EntandoApp, making it possible to reach those APIs from the EntandoApp using relative urls. -This is the standard flow when no other micorservice with a given name is already available in the EntandoApp namespace. +This is the standard flow when no other micorservice with the same name is already present in the EntandoApp namespace. If there is an existing microservice with the same name as the one generated from the PluginDescriptor, the Local Hub will connect the EntandoApp to -the existing microservice by generating and deploying the required EntandoAppPluginLink per step 3 above. +the existing microservice by generating and deploying the required EntandoAppPluginLink per step three above. This way, plugins can be reused by many applications at the same time. ## Other Options -The naming convention recommendations above are accurate for creating bundles and for self contained applications where the Entando operator is managing the lifecycle of your microservices. If you have a substantial API infrastructure or you intend to deploy a large number of versioned microservices you can also utilize Entando with API management infrastructure like API gateways. If you are using an API gateway or other API abstraction layer you will need to manually manage the ingress for your micro frontends in your application to point to the API gateway deployment. +The naming convention recommended above are accurate for creating bundles and for self contained applications where the Entando Operator is managing the lifecycle of your microservices. If you have a substantial API infrastructure or intend to deploy a large number of versioned microservices, you can also utilize an API management infrastructure like API gateways. If you use an API gateway or other API abstraction layer, you will need to manually manage the ingress for the micro frontends in your application to point to the API gateway deployment. -In cases where conflicts occur bundles can easily be renamed by updating metdata. +In cases where conflicts occur, bundles can easily be renamed by updating metdata. -## Kubernetes naming conventions +## Kubernetes Naming Conventions -Here some rules about naming conventions extracted from the [Kubernetes documentation on object names and ids](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/) +Here are a few recommendations about naming conventions extracted from the [Kubernetes documentation on object names and ids](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/). -> Most resource types require a name that can be used as a DNS subdomain name as defined in RFC 1123. This means the name must: -> - contain no more than 253 characters -> - contain only lowercase alphanumeric characters, '-' or '.' -> - start with an alphanumeric character -> - end with an alphanumeric character +Most resource types require a name that can be used as a DNS subdomain name as defined in RFC 1123. This means the name must: + - contain no more than 253 characters + - contain only lowercase alphanumeric characters, '-' or '.' + - start with an alphanumeric character + - end with an alphanumeric character