From 3f6d8ecc578d15062c627d63411bc5cc901ff8e7 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 2 Feb 2023 09:52:47 -0600 Subject: [PATCH 1/5] ENDOC-648 consolidate bundle version upgrade --- vuepress/docs/.vuepress/next.js | 4 + .../docs/next/docs/curate/bundle-details.md | 2 +- .../bundle-comparison.md | 10 +- .../next/docs/reference/bundle-upgrade.md | 136 ++++++++++++++++++ 4 files changed, 143 insertions(+), 9 deletions(-) rename vuepress/docs/next/docs/{curate => reference}/bundle-comparison.md (72%) create mode 100644 vuepress/docs/next/docs/reference/bundle-upgrade.md 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 4f310b7695..3b5d820f93 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 of 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 72% rename from vuepress/docs/next/docs/curate/bundle-comparison.md rename to vuepress/docs/next/docs/reference/bundle-comparison.md index dd6bd00da2..1d31827a36 100644 --- a/vuepress/docs/next/docs/curate/bundle-comparison.md +++ b/vuepress/docs/next/docs/reference/bundle-comparison.md @@ -4,16 +4,10 @@ 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 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. -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](bundle-details.md) page for specification and the guide on how to [upgrade to docker-based bundles](./bundle-upgrade.md). -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)| | :- | :-------------------- | :--------------------- | 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..3086f36594 --- /dev/null +++ b/vuepress/docs/next/docs/reference/bundle-upgrade.md @@ -0,0 +1,136 @@ +--- +sidebarDepth: 2 +--- + +# Bundles Upgrade Guideline + +Two types of bundles can be utilized on Entando 7.1+. The original git-based bundle added a composable method with reusable components. The newly introduced docker-based bundles optimize their structure and expands functionality. The [Bundle Evolution Comparison](./bundle-comparison.md) table lists the differences between the two types. The following page describes the guidelines for upgrading to docker-based v5 bundles. + +Git-based bundles do not need to be to upgraded. Both types of bundles are compatible on Entando 7.1+, but docker-based bundles provide several innovations and an improved developer experience. + +The improvements include: +* Simplified bundle directory structure +* A decoupled build and deployment process that is easier to understand, modify, and troubleshoot +* CI/CD integration and support +* One Git source repository required with Docker image repositories created automatically as needed +* Optimized file storage and transfer methods using a layered file system, beneficial for large projects +* Standardized bundle address format + +## Quick Reference +* [Bundle Specifications](../curate/bundle-details.md) + +* [Bundle Management](../getting-started/ent-bundle.md) + +* [Bundle Version Comparison Table](./bundle-comparison.md) + +## Upgrade Process + +### Initialize Bundle + +1. Initialize a new bundle to set up the standard Entando Bundle structure using the ent CLI: + +``` +ent bundle init YOUR-BUNDLE-NAME +``` +### 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. `YOUR-BUNDLE-NAME/platform` directory is designated for resources such as fragments, contents, pages, and templates. Copy the output of the ent bundler to this folder. You can also accomplish this manually but there are advantages to the bundler such as generating top level descriptors for platform resources. +Note that widgets that are not MFEs are considered platform entities on Entando and should be placed in the `platform/widgets` directory. + +### Add Micro Frontends & Microservices + +1. Add your micro frontend to the new bundle descriptor `entando.json`: +``` sh +ent bundle mfe add YOUR-MFE1 +``` +The docker-based bundle has a centralized bundle descriptor with bundle entities such as micro frontends, microservices, APIs, DBMS, and ID management specifications. + +2. Copy the MFE files into `YOUR-BUNDLE-NAME/microfrontends` directory. For instance, for an MFE named YOUR-MFE1: + +``` sh +mv YOUR-ORIGIN-DIRECTORY/YOUR-MFE1/{.,}* microfrontends/YOUR-MFE1 +``` +Micro frontends and microservices are partitioned into their own directories in the docker-based bundles to streamline the CI/CD process. + +3. Add your microservice: +``` sh +ent bundle ms add YOUR-MS1 +``` +4. Copy the microservice YOUR-MS1 files to the new location: +``` sh +mv YOUR-ORIGIN-DIRECTORY/YOUR-MS1/{.,}* microservicess/YOUR-MS1 +``` +5. Repeat steps 1 through 4 for all micro frontends and microservices. + +### Add API Claims +1. Now add an API claim to connect the `YOUR-MFE1` to a microsersive as needed. The connection information is added to the descriptor `entando.json`. +```shell +ent bundle api add YOUR-MFE1 YOUR-API --serviceName=YOUR-MS1 --serviceUrl=http://localhost:8081 +``` + +2. Repeat the previous step for all APIs as needed. + +### Add Custom Commands to Test Locally + +1. For local development and testing, a custom command is needed in the `entando.json` to use a different port for each MFE as shown below: +``` + "microfrontends": [ + { + "name": "YOUR-MFE1", + "customElement": "YOUR-MFE1", + "stack": "react", + "type": "widget", + "group": "free", + "publicFolder": "public", + "commands": { + "run": "npm install && PORT=3000 npm start" + }, + "apiClaims": [ + { + "name": "YOUR-API1", + "type": "internal", + "serviceName": "YOUR-MS1" + } + ] + }, + { + "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" + } + ] + } + ] +``` +Note that in production, all microservices must run on port 8081. + +### Add Auxiliary Services +Copy the 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 +``` +### Pack and Install +With the bundle project files in place and tested, [build and install](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) + + From 7dbe9417ae108fa0b058a1f5f8ea1a07e78fe00c Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 2 Feb 2023 10:08:39 -0600 Subject: [PATCH 2/5] ENDOC-648 upgrade bundle correct links --- vuepress/docs/next/docs/reference/bundle-comparison.md | 8 ++++---- vuepress/docs/next/docs/reference/bundle-upgrade.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/vuepress/docs/next/docs/reference/bundle-comparison.md b/vuepress/docs/next/docs/reference/bundle-comparison.md index 1d31827a36..f27d12924f 100644 --- a/vuepress/docs/next/docs/reference/bundle-comparison.md +++ b/vuepress/docs/next/docs/reference/bundle-comparison.md @@ -6,15 +6,15 @@ sidebarDepth: 2 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 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. -For more information on docker-based bundles, see the [Bundle Details](bundle-details.md) page for specification and the guide on how to [upgrade to docker-based bundles](./bundle-upgrade.md). +For more information on docker-based bundles, see the [Bundle Details](../curate/bundle-details.md) page for specification and the guide on how to [upgrade to docker-based bundles](./bundle-upgrade.md). ### 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 index 3086f36594..f472e6cb01 100644 --- a/vuepress/docs/next/docs/reference/bundle-upgrade.md +++ b/vuepress/docs/next/docs/reference/bundle-upgrade.md @@ -127,7 +127,7 @@ mv YOUR-ORIGIN-DIRECTORY/* svc/ ent bundle svc enable keycloak ``` ### Pack and Install -With the bundle project files in place and tested, [build and install](publish-project-bundle.md) your bundle. +With the bundle project files in place and tested, [build and install](../../tutorials/create/pb/publish-project-bundle.md) your bundle. From ccf8ea7b80b2fa0115add01d0ea6bea60a0ab589 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Mon, 6 Feb 2023 14:49:19 -0600 Subject: [PATCH 3/5] ENDOC-648 bundle upgrade edits --- .../docs/next/docs/curate/bundle-details.md | 2 +- .../next/docs/reference/bundle-comparison.md | 4 +- .../next/docs/reference/bundle-upgrade.md | 57 ++++++++++--------- 3 files changed, 32 insertions(+), 31 deletions(-) diff --git a/vuepress/docs/next/docs/curate/bundle-details.md b/vuepress/docs/next/docs/curate/bundle-details.md index 3b5d820f93..e9956cf0b1 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](../reference/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/reference/bundle-comparison.md b/vuepress/docs/next/docs/reference/bundle-comparison.md index f27d12924f..2c8a220321 100644 --- a/vuepress/docs/next/docs/reference/bundle-comparison.md +++ b/vuepress/docs/next/docs/reference/bundle-comparison.md @@ -4,9 +4,9 @@ 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 bundle project. 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. +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. -For more information on docker-based bundles, see the [Bundle Details](../curate/bundle-details.md) page for specification and the guide on how to [upgrade to docker-based bundles](./bundle-upgrade.md). +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. ### Bundle Comparison Table |Property| [git-based bundles](../../../v7.0/docs/curate/ecr-bundle-details.md)| [docker-based bundles](../curate/bundle-details.md)| diff --git a/vuepress/docs/next/docs/reference/bundle-upgrade.md b/vuepress/docs/next/docs/reference/bundle-upgrade.md index f472e6cb01..4f2c3a7939 100644 --- a/vuepress/docs/next/docs/reference/bundle-upgrade.md +++ b/vuepress/docs/next/docs/reference/bundle-upgrade.md @@ -2,19 +2,19 @@ sidebarDepth: 2 --- -# Bundles Upgrade Guideline +# Bundle Upgrade Guideline -Two types of bundles can be utilized on Entando 7.1+. The original git-based bundle added a composable method with reusable components. The newly introduced docker-based bundles optimize their structure and expands functionality. The [Bundle Evolution Comparison](./bundle-comparison.md) table lists the differences between the two types. The following page describes the guidelines for upgrading to docker-based v5 bundles. - -Git-based bundles do not need to be to upgraded. Both types of bundles are compatible on Entando 7.1+, but docker-based bundles provide several innovations and an improved developer experience. +This guideline describes the process for upgrading a git-based bundle to the newly introduced docker-based bundle (v5). + +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: -* Simplified bundle directory structure +* A simplified bundle directory structure * A decoupled build and deployment process that is easier to understand, modify, and troubleshoot * CI/CD integration and support -* One Git source repository required with Docker image repositories created automatically as needed +* 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 -* Standardized bundle address format +* A standardized bundle address format ## Quick Reference * [Bundle Specifications](../curate/bundle-details.md) @@ -25,55 +25,57 @@ The improvements include: ## Upgrade Process -### Initialize Bundle +### 1. Initialize Bundle -1. Initialize a new bundle to set up the standard Entando Bundle structure using the ent CLI: +Initialize a new bundle to set up the docker-based bundle structure using the ent CLI: ``` ent bundle init YOUR-BUNDLE-NAME ``` -### Copy Assets +### 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. `YOUR-BUNDLE-NAME/platform` directory is designated for resources such as fragments, contents, pages, and templates. Copy the output of the ent bundler to this folder. You can also accomplish this manually but there are advantages to the bundler such as generating top level descriptors for platform resources. -Note that widgets that are not MFEs are considered platform entities on Entando and should be placed in the `platform/widgets` directory. +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. -### Add Micro Frontends & Microservices +### 3. Add Micro Frontends & Microservices -1. Add your micro frontend to the new bundle descriptor `entando.json`: +1. From inside your bundle project folder, add your micro frontend to the bundle descriptor `entando.json`: ``` sh ent bundle mfe add YOUR-MFE1 ``` -The docker-based bundle has a centralized bundle descriptor with bundle entities such as micro frontends, microservices, APIs, DBMS, and ID management specifications. +>Docker-based bundles have a centralized bundle descriptor that includes specifications for bundle entities such as micro frontends, microservices, APIs, DBMS, and ID management. -2. Copy the MFE files into `YOUR-BUNDLE-NAME/microfrontends` directory. For instance, for an MFE named YOUR-MFE1: +2. Copy the MFE files into the `YOUR-BUNDLE-NAME/microfrontends` directory. For instance, for an MFE named YOUR-MFE1: ``` sh mv YOUR-ORIGIN-DIRECTORY/YOUR-MFE1/{.,}* microfrontends/YOUR-MFE1 ``` -Micro frontends and microservices are partitioned into their own directories in the docker-based bundles to streamline the CI/CD process. +>Micro frontends and microservices are partitioned into their own directories in v5 bundles to streamline the CI/CD process. 3. Add your microservice: ``` sh ent bundle ms add YOUR-MS1 ``` -4. Copy the microservice YOUR-MS1 files to the new location: +4. Copy YOUR-MS1 files to the new location: ``` sh mv YOUR-ORIGIN-DIRECTORY/YOUR-MS1/{.,}* microservicess/YOUR-MS1 ``` 5. Repeat steps 1 through 4 for all micro frontends and microservices. -### Add API Claims -1. Now add an API claim to connect the `YOUR-MFE1` to a microsersive as needed. The connection information is added to the descriptor `entando.json`. +### 4. Add API Claims +1. Add an API claim to connect `YOUR-MFE1` to a microsersive as needed. The connection information is added to the descriptor `entando.json`. ```shell ent bundle api add YOUR-MFE1 YOUR-API --serviceName=YOUR-MS1 --serviceUrl=http://localhost:8081 ``` 2. Repeat the previous step for all APIs as needed. -### Add Custom Commands to Test Locally +### 5. Add Custom Commands to Test Locally -1. For local development and testing, a custom command is needed in the `entando.json` to use a different port for each MFE as shown below: +For local development and testing, a custom command is needed in the `entando.json` to use a different port for each MFE as shown below: ``` "microfrontends": [ { @@ -118,19 +120,18 @@ ent bundle api add YOUR-MFE1 YOUR-API --serviceName=YOUR-MS1 --serviceUrl=http:/ } ] ``` -Note that in production, all microservices must run on port 8081. +>In production, all microservices must run on port 8081. -### Add Auxiliary Services -Copy the auxiliary services such as DBMS or Keycloak into the `svc` directory as needed and enable them for local testing. For a Keycloak service: +### 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 ``` -### Pack and Install +### 7. Pack and Install With the bundle project files in place and tested, [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) +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). From 06d5138a1b5eeed616f3b69772bd8c4f38a5cbb3 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Tue, 7 Feb 2023 08:46:34 -0600 Subject: [PATCH 4/5] ENDOC-648 more edits --- vuepress/docs/next/docs/reference/bundle-upgrade.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/vuepress/docs/next/docs/reference/bundle-upgrade.md b/vuepress/docs/next/docs/reference/bundle-upgrade.md index 4f2c3a7939..0f8e8ce02f 100644 --- a/vuepress/docs/next/docs/reference/bundle-upgrade.md +++ b/vuepress/docs/next/docs/reference/bundle-upgrade.md @@ -73,6 +73,8 @@ ent bundle api add YOUR-MFE1 YOUR-API --serviceName=YOUR-MS1 --serviceUrl=http:/ 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 For local development and testing, a custom command is needed in the `entando.json` to use a different port for each MFE as shown below: @@ -128,6 +130,8 @@ Copy auxiliary services such as DBMS or Keycloak into the `svc` directory as nee 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 With the bundle project files in place and tested, [build and install](../../tutorials/create/pb/publish-project-bundle.md) your bundle. From 76216dc74481f2749cfcc7aa772f9d9324393c3a Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Wed, 8 Feb 2023 13:22:04 -0600 Subject: [PATCH 5/5] ENDOC-648 upgrade bundle edits --- .../next/docs/reference/bundle-upgrade.md | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/vuepress/docs/next/docs/reference/bundle-upgrade.md b/vuepress/docs/next/docs/reference/bundle-upgrade.md index 0f8e8ce02f..997166cd2f 100644 --- a/vuepress/docs/next/docs/reference/bundle-upgrade.md +++ b/vuepress/docs/next/docs/reference/bundle-upgrade.md @@ -4,7 +4,7 @@ sidebarDepth: 2 # Bundle Upgrade Guideline -This guideline describes the process for upgrading a git-based bundle to the newly introduced docker-based bundle (v5). +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. @@ -16,7 +16,7 @@ The improvements include: * Optimized file storage and transfer methods using a layered file system, beneficial for large projects * A standardized bundle address format -## Quick Reference +## Quick References * [Bundle Specifications](../curate/bundle-details.md) * [Bundle Management](../getting-started/ent-bundle.md) @@ -44,45 +44,45 @@ ent bundle init YOUR-BUNDLE-NAME 1. From inside your bundle project folder, add your micro frontend to the bundle descriptor `entando.json`: ``` sh -ent bundle mfe add YOUR-MFE1 +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, APIs, DBMS, and ID management. +>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 the `YOUR-BUNDLE-NAME/microfrontends` directory. For instance, for an MFE named YOUR-MFE1: +2. Copy the MFE files into `YOUR-BUNDLE-NAME/microfrontends`. For instance, for an MFE named YOUR-MFE: ``` sh -mv YOUR-ORIGIN-DIRECTORY/YOUR-MFE1/{.,}* microfrontends/YOUR-MFE1 +mv YOUR-ORIGIN-DIRECTORY/YOUR-MFE/{.,}* microfrontends/YOUR-MFE ``` ->Micro frontends and microservices are partitioned into their own directories in v5 bundles to streamline the CI/CD process. +>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-MS1 +ent bundle ms add YOUR-MS ``` -4. Copy YOUR-MS1 files to the new location: +4. Copy YOUR-MS files to the new location: ``` sh -mv YOUR-ORIGIN-DIRECTORY/YOUR-MS1/{.,}* microservicess/YOUR-MS1 +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-MFE1` to a microsersive as needed. The connection information is added to the descriptor `entando.json`. +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-MFE1 YOUR-API --serviceName=YOUR-MS1 --serviceUrl=http://localhost:8081 +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 +### 5. Add Custom Commands to Test Locally (Optional) -For local development and testing, a custom command is needed in the `entando.json` to use a different port for each MFE as shown below: +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-MFE1", - "customElement": "YOUR-MFE1", + "name": "YOUR-MFE", + "customElement": "YOUR-MFE", "stack": "react", "type": "widget", "group": "free", @@ -92,9 +92,9 @@ For local development and testing, a custom command is needed in the `entando.js }, "apiClaims": [ { - "name": "YOUR-API1", + "name": "YOUR-API", "type": "internal", - "serviceName": "YOUR-MS1" + "serviceName": "YOUR-MS" } ] }, @@ -133,7 +133,7 @@ ent bundle svc enable keycloak >For details on adding services, see the [Auxiliary Services](../getting-started/ent-svc.md) page. ### 7. Pack and Install -With the bundle project files in place and tested, [build and install](../../tutorials/create/pb/publish-project-bundle.md) your bundle. +[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).