diff --git a/vuepress/docs/.vuepress/next.js b/vuepress/docs/.vuepress/next.js index 4998d70bec..0b23541d92 100644 --- a/vuepress/docs/.vuepress/next.js +++ b/vuepress/docs/.vuepress/next.js @@ -181,6 +181,10 @@ module.exports = { title: 'Databases', path: path + 'reference/databases.md' }, + { + title: 'Bundle Upgrade', + path: path + 'reference/bundle-upgrade.md' + }, { title: 'Caching and Clustering', path: path + 'reference/caching-and-clustering.md' diff --git a/vuepress/docs/next/docs/curate/bundle-details.md b/vuepress/docs/next/docs/curate/bundle-details.md index 25888f5680..3c124c2172 100644 --- a/vuepress/docs/next/docs/curate/bundle-details.md +++ b/vuepress/docs/next/docs/curate/bundle-details.md @@ -6,7 +6,7 @@ sidebarDepth: 2 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 docker-based approach is an improvement of the previous Entando Bundle structure and to see the differences, refer to the [Bundle Evolution](bundle-comparison.md) page. +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 diff --git a/vuepress/docs/next/docs/curate/bundle-comparison.md b/vuepress/docs/next/docs/reference/bundle-comparison.md similarity index 67% rename from vuepress/docs/next/docs/curate/bundle-comparison.md rename to vuepress/docs/next/docs/reference/bundle-comparison.md index dd6bd00da2..2c8a220321 100644 --- a/vuepress/docs/next/docs/curate/bundle-comparison.md +++ b/vuepress/docs/next/docs/reference/bundle-comparison.md @@ -4,23 +4,17 @@ sidebarDepth: 2 # Bundle Evolution on Entando 7.1 -Entando 7.1 implements a more modular approach to building apps with the **ent bundle CLI** orchestrating the management of project bundles. The Entando Bundle was restructured, its processes decoupled by component type, and the publishing transport method was streamlined. With these changes, Entando Bundles went from git-based to docker-based OCI bundles. Both types are supported on Entando 7.1, and this page clarifies the differences between the two, along with the improvements in the new release. +Entando 7.1 implements a more modular approach to building apps with the **ent bundle CLI** orchestrating the management of bundle project. The Entando Bundle was restructured, its processes decoupled by component type, and the publishing transport method streamlined. With these changes, Entando Bundles went from git-based to docker-based OCI bundles. Both types are supported on Entando 7.1, and this page clarifies the differences between the two. -Some of the major improvements with docker-based bundles are: -* Simplified bundle directory structure -* Just one Git source repository required with Docker image repositories created automatically as needed -* Optimized file storage and transfer using a layered file system, beneficial for large projects -* Standardized bundle address format -* A decoupled build and deployment process which is easier to understand, modify, and troubleshoot +For more information on docker-based bundles, see the [Bundle Details](../curate/bundle-details.md) page for specifications and the [upgrade guideline](./bundle-upgrade.md) for general instructions on converting a git-based bundle. -For specifications on docker-based bundles, see the [Bundle Details](bundle-details.md) page. ### Bundle Comparison Table -|Property| [git-based bundles](../../../v7.0/docs/curate/ecr-bundle-details.md)| [docker-based bundles](bundle-details.md)| +|Property| [git-based bundles](../../../v7.0/docs/curate/ecr-bundle-details.md)| [docker-based bundles](../curate/bundle-details.md)| | :- | :-------------------- | :--------------------- | |`descriptorVersion`| v1| v5 | Bundle Specifications |Defined with descriptor files | Built with [ent bundle CLI](../getting-started/ent-bundle.md) tool -| Versioning |Bundle version set by Git tags |Bundle version set by Docker tags. For MFEs, the version defaults to 1.0.0 unless set in the [entando.json](bundle-details.md) -|Plugin Ingress| Generated by Entando or set in the plugin descriptor.yaml | Generated by Entando or customized in the [bundle descriptor](bundle-details.md#entando-bundle-conventions), entando.json +| Versioning |Bundle version set by Git tags |Bundle version set by Docker tags. For MFEs, the version defaults to 1.0.0 unless set in the [entando.json](../curate/bundle-details.md) +|Plugin Ingress| Generated by Entando or set in the plugin descriptor.yaml | Generated by Entando or customized in the [bundle descriptor](../curate/bundle-details.md#entando-bundle-conventions), entando.json |Identifiers| Designated Bundle ID and Plugin ID | Bundles, MFEs, & plugins have unique global IDs| |Bundle ID| Not included in component names | Suffix of bundle, plugin, widget, page and fragment names |Initialize from Entando Hub| As git clone |[Direct initialization from Hub](../getting-started/ent-bundle.md#initialization) with `–from-hub` flag| diff --git a/vuepress/docs/next/docs/reference/bundle-upgrade.md b/vuepress/docs/next/docs/reference/bundle-upgrade.md new file mode 100644 index 0000000000..997166cd2f --- /dev/null +++ b/vuepress/docs/next/docs/reference/bundle-upgrade.md @@ -0,0 +1,141 @@ +--- +sidebarDepth: 2 +--- + +# Bundle Upgrade Guideline + +This guideline describes the process for upgrading a git-based bundle to the docker-based bundle (v5) introduced in Entando 7.1. + +Git-based bundles do not need to be to upgraded. Both types of bundles are compatible with Entando 7.1+, but the v5 bundles provide several innovations and an improved developer experience. + +The improvements include: +* A simplified bundle directory structure +* A decoupled build and deployment process that is easier to understand, modify, and troubleshoot +* CI/CD integration and support +* A single required Git source repository with Docker image repositories created automatically as needed +* Optimized file storage and transfer methods using a layered file system, beneficial for large projects +* A standardized bundle address format + +## Quick References +* [Bundle Specifications](../curate/bundle-details.md) + +* [Bundle Management](../getting-started/ent-bundle.md) + +* [Bundle Version Comparison Table](./bundle-comparison.md) + +## Upgrade Process + +### 1. Initialize Bundle + +Initialize a new bundle to set up the docker-based bundle structure using the ent CLI: + +``` +ent bundle init YOUR-BUNDLE-NAME +``` +### 2. Copy Assets +1. Use the ent CLI bundler command to export assets from an existing Entando Bundle. See the step-by-step [Export and Publish Tutorial](../../tutorials/create/pb/export-bundle-from-application.md). + +2. The `platform` directory is designated for resources such as fragments, contents, pages, and templates. Copy the output of the ent bundler to 'YOUR-BUNDLE-NAME/platform`. + +>-You can also accomplish this manually, but the ent bundler can automatically generate top-level descriptors for platform resources. +-Widgets that are not MFEs are considered platform entities on Entando and should be placed in the `platform/widgets` directory. + +### 3. Add Micro Frontends & Microservices + +1. From inside your bundle project folder, add your micro frontend to the bundle descriptor `entando.json`: +``` sh +ent bundle mfe add YOUR-MFE +``` +>Docker-based bundles have a centralized bundle descriptor that includes specifications for bundle entities such as micro frontends, microservices, and platform components. + +2. Copy the MFE files into `YOUR-BUNDLE-NAME/microfrontends`. For instance, for an MFE named YOUR-MFE: + +``` sh +mv YOUR-ORIGIN-DIRECTORY/YOUR-MFE/{.,}* microfrontends/YOUR-MFE +``` +>Micro frontends and microservices are placed in their own directories in v5 bundles to streamline the CI/CD process. + +3. Add your microservice: +``` sh +ent bundle ms add YOUR-MS +``` +4. Copy YOUR-MS files to the new location: +``` sh +mv YOUR-ORIGIN-DIRECTORY/YOUR-MS/{.,}* microservicess/YOUR-MS +``` +5. Repeat steps 1 through 4 for all micro frontends and microservices. + +### 4. Add API Claims +1. Add an API claim to connect `YOUR-MFE` to a microservice as needed. The connection information is added to the descriptor `entando.json`. +```shell +ent bundle api add YOUR-MFE YOUR-API --serviceName=YOUR-MS --serviceUrl=http://localhost:8081 +``` + +2. Repeat the previous step for all APIs as needed. + +>Refer to the [API Management](../getting-started/ent-api.md) page for additional information. + +### 5. Add Custom Commands to Test Locally (Optional) + +For local development and testing, a custom command can be provided in the `entando.json` to specify a different port for each MFE as shown below: +``` + "microfrontends": [ + { + "name": "YOUR-MFE", + "customElement": "YOUR-MFE", + "stack": "react", + "type": "widget", + "group": "free", + "publicFolder": "public", + "commands": { + "run": "npm install && PORT=3000 npm start" + }, + "apiClaims": [ + { + "name": "YOUR-API", + "type": "internal", + "serviceName": "YOUR-MS" + } + ] + }, + { + "name": "YOUR-MFE2", + "customElement": "YOUR-MFE2", + "stack": "react", + "type": "widget", + "group": "free", + "publicFolder": "public", + "titles": { + "en": "YOUR-MFE2", + "it": "YOUR-MFE2" + }, + "commands": { + "run": "npm install && PORT=3001 npm start" + }, + "apiClaims": [ + { + "name": "YOUR-API2", + "type": "internal", + "serviceName": "YOUR-MS2" + } + ] + } + ] +``` +>In production, all microservices must run on port 8081. + +### 6. Add Auxiliary Services +Copy auxiliary services such as DBMS or Keycloak into the `svc` directory as needed and enable them for local testing. For a Keycloak service: +``` sh +mv YOUR-ORIGIN-DIRECTORY/* svc/ +ent bundle svc enable keycloak +``` +>For details on adding services, see the [Auxiliary Services](../getting-started/ent-svc.md) page. + +### 7. Pack and Install +[Build and install](../../tutorials/create/pb/publish-project-bundle.md) your bundle. + + +For an example tutorial, see [Generate Microservices and Micro Frontends](https://developer.entando.com/next/tutorials/create/ms/generate-microservices-and-micro-frontends.html#configure-the-components). + +