From 54e910069a9a8d8caf476ddc33174dbd8b59e1a3 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Wed, 5 Oct 2022 10:31:46 -0500 Subject: [PATCH 1/3] ENDOC-534 export-publish tutorial --- .../pb/export-bundle-from-application.md | 63 ++++++++++++------- 1 file changed, 39 insertions(+), 24 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md b/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md index aa011d0641..8b6f3f75fc 100644 --- a/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md +++ b/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md @@ -3,29 +3,24 @@ sidebarDepth: 2 --- # Export and Publish a Bundle -## Overview -Use the bundler command to export a bundle of components from an existing Entando Application. An Entando Bundle can be used -- For the initial install of Entando components into an Entando Application -- To migrate Entando components from one environment to another (e.g. Dev to QA) -- To provide a template for building a new Entando Application -- As the skeleton of an Entando solution +The ent bundler command can export a bundle from an existing Entando Application to be utilized in the following ways: +- For the initial install of components into an Entando Application +- To migrate bundles from one environment to another (e.g. Dev to QA) +- To provide a template for building a new application -This command generates the same bundle directory structure as an Entando project, including a bundle descriptor file. +This tutorial illustrates how to use the ent bundler to export a git-based Entando Bundle. This package can be deployed to a running Entando instance or modified to a docker-based bundle to take advantage of Entando's latest composable methods. The procedure assumes you're using an Entando quickstart application. Otherwise, you may need to adjust specific URLs, credentials, namespaces, etc., for a custom application. + +## Prerequisites +* [A running instance of Entando](../../../docs/getting-started/) +* Verify dependencies with the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment): `ent check-env develop` -### Prerequisites -* Use the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment) to verify prerequisites (e.g. git, entando-bundler): -``` sh -ent check-env develop -``` -* A running Entando Application * [Admin access to Keycloak](../../../docs/consume/identity-management.md#logging-into-your-keycloak-instance) -This tutorial assumes you're using an Entando quickstart application. You may need to adjust specific URLs, credentials, namespaces, etc., for a custom application. ## Export an Entando Bundle ### Set Up the Keycloak Client -Configure a Keycloak client to grant the bundler access to the required Entando APIs. +Configure a Keycloak client to grant the ent CLI access to the required Entando APIs. 1. Log in to Keycloak using the admin credentials. The URL will be similar to `http://YOUR-HOST-NAME/auth/` and can be verified with the following command: ``` sh @@ -36,10 +31,10 @@ kubectl describe ingress/default-sso-in-namespace-ingress -n entando 3. Enter a `Client ID` of your choice, e.g. `entando-bundler` 4. Click `Save` 5. The `Settings` tab should be shown. Edit the values as follows: -* `Access Type`: confidential -* `Service Accounts Enabled`: On -* `Valid Redirect URLs`: * -* `Web Origins`: * + * `Access Type`: confidential + * `Service Accounts Enabled`: On + * `Valid Redirect URLs`: * + * `Web Origins`: * 6. Click `Save` 7. Go to the `Service Account Roles` tab @@ -48,8 +43,8 @@ kubectl describe ingress/default-sso-in-namespace-ingress -n entando 10. Click `Add Selected` to add `superuser` to the `Assigned Roles`. This change will be saved automatically. 11. Go to the `Credentials` tab and copy the `Secret` shown there for use in the next section -### Create env.json -1. Create a directory where you'll run the bundler and go to that directory: +### Create the `env.json` +1. Create a directory where you'll run the bundler and switch to that directory: ```sh mkdir testBundle; cd testBundle ``` @@ -71,9 +66,9 @@ mkdir bundle ``` 2. Run the bundler: ``` sh -ent bundler from-env --location bundle --code YOUR-TEST-BUNDLE --description “Your Test Bundle” +ent bundler from-env --location bundle --code YOUR-BUNDLE-NAME --description “Your Exported Bundle” ``` -The bundler will inspect the application using Entando APIs, collect information about individual components, construct appropriate descriptor files and assemble the top-level descriptor file. +The bundler will inspect the application using Entando APIs, collect information about individual components, construct appropriate descriptor files, and assemble the top-level descriptor file. ``` $ ls bundle @@ -81,4 +76,24 @@ assets contentModels contents fragments labels pageModels re categories contentTypes descriptor.yaml groups languages pages widgets ``` -You now have a complete Entando project structure! You can inspect the output to edit the exported components or deploy it to another Entando Application. +You now have a complete Entando project structure for a git-based bundle! You can inspect the output to edit the exported components or [deploy](publish-project-bundle.md) it to another Entando Application. +::: tip Note: +To convert this project to a docker-based bundle, continue with the steps below. +::: + +### Construct the Docker-based Bundle Structure + +1. Initialize a new bundle and switch to that directory: +``` +ent bundle init YOUR-BUNDLE-NAME +cd YOUR-BUNDLE-NAME +``` +2. Copy the resources from the bundle directory, with the exception of microservices (/plugins) and micro frontends (/widgets), to the `platform` directory: +``` +cp -R ../testBundle/bundle/assets platform/ +``` +Repeat for all the other components in your bundle, including assets, contentModels, contents, fragments, labels, pageModels, resources, categories, contentTypes, groups, languages, and pages. + +If there are micro frontends or microservices in the bundle, use the source code to migrate them to their designated folders. Use the [ent bundle CLI tool](../../../docs/getting-started/ent-bundle.md) to assist in the process. Also check out the [Entando Bundle details](../../../docs/curate/bundle-details.md) page to define specific attributes for the MFEs and MSs in the bundle descriptor, `entando.json`. + +3. With the project structure in place, [build and publish](publish-project-bundle.md) your bundle. \ No newline at end of file From fbfeda2788212cd7044523f2362e51f75f0b1ee7 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 6 Oct 2022 08:38:45 -0500 Subject: [PATCH 2/3] ENDOC-534 language edit --- .../pb/export-bundle-from-application.md | 36 +++++++++++-------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md b/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md index 8b6f3f75fc..47cbb79e63 100644 --- a/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md +++ b/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md @@ -3,12 +3,12 @@ sidebarDepth: 2 --- # Export and Publish a Bundle -The ent bundler command can export a bundle from an existing Entando Application to be utilized in the following ways: -- For the initial install of components into an Entando Application -- To migrate bundles from one environment to another (e.g. Dev to QA) -- To provide a template for building a new application +The ent bundler command exports a bundle from an existing Entando Application to: +- Perform the initial install of components into an Entando Application +- Migrate bundles from one environment to another (e.g. Dev to QA) +- Provide a template for building a new application -This tutorial illustrates how to use the ent bundler to export a git-based Entando Bundle. This package can be deployed to a running Entando instance or modified to a docker-based bundle to take advantage of Entando's latest composable methods. The procedure assumes you're using an Entando quickstart application. Otherwise, you may need to adjust specific URLs, credentials, namespaces, etc., for a custom application. +This tutorial describes how to export a git-based Entando Bundle using the ent CLI. This package can be deployed to Entando or changed to a docker-based bundle to take advantage of Entando's latest composable methods. The procedure assumes you're using an Entando quickstart application. Otherwise, you may need to adjust specific URLs, credentials, namespaces, etc., for a custom application. ## Prerequisites * [A running instance of Entando](../../../docs/getting-started/) @@ -43,12 +43,12 @@ kubectl describe ingress/default-sso-in-namespace-ingress -n entando 10. Click `Add Selected` to add `superuser` to the `Assigned Roles`. This change will be saved automatically. 11. Go to the `Credentials` tab and copy the `Secret` shown there for use in the next section -### Create the `env.json` +### Create the `env.json` Configuration File 1. Create a directory where you'll run the bundler and switch to that directory: ```sh mkdir testBundle; cd testBundle ``` -2. Create an `env.json` file with the environment URLs and client credentials. Refer to the [client configuration](#set-up-the-keycloak-client) for the `clientId` and `clientSecret` values. +2. Create an `env.json` file using your environment URLs and client credentials. Refer to the [client configuration](#set-up-the-keycloak-client) for the `clientId` and `clientSecret` values. ``` json { @@ -88,12 +88,20 @@ To convert this project to a docker-based bundle, continue with the steps below. ent bundle init YOUR-BUNDLE-NAME cd YOUR-BUNDLE-NAME ``` -2. Copy the resources from the bundle directory, with the exception of microservices (/plugins) and micro frontends (/widgets), to the `platform` directory: -``` -cp -R ../testBundle/bundle/assets platform/ -``` -Repeat for all the other components in your bundle, including assets, contentModels, contents, fragments, labels, pageModels, resources, categories, contentTypes, groups, languages, and pages. +2. Copy the resources from the `testBundle/bundle` directory to the `YOUR-BUNDLE-NAME/platform` directory, with the exception of microservices (/plugins) and micro frontends (/widgets). + +For micro frontends and microservices, use the source code to migrate them manually to the corresponding folders inside your bundle directory. Note that non-MFE widgets are considered platform entities on Entando and should be placed in the `platform/widgets` directory. -If there are micro frontends or microservices in the bundle, use the source code to migrate them to their designated folders. Use the [ent bundle CLI tool](../../../docs/getting-started/ent-bundle.md) to assist in the process. Also check out the [Entando Bundle details](../../../docs/curate/bundle-details.md) page to define specific attributes for the MFEs and MSs in the bundle descriptor, `entando.json`. +Use the [ent bundle CLI tool](../../../docs/getting-started/ent-bundle.md) to assist in the process of adding micro frontends and microservices. To define their specific attributes in the bundle descriptor, `entando.json`, also check out the [Entando Bundle details](../../../docs/curate/bundle-details.md) page. -3. With the project structure in place, [build and publish](publish-project-bundle.md) your bundle. \ No newline at end of file +3. With the project structure in place, [build and publish](publish-project-bundle.md) your bundle. +``` +ent bundle pack +ent bundle publish +ent bundle deploy +ent bundle install +``` +**Next Steps** +* [Manage APIs](../../../docs/getting-started/ent-api.md) for your bundle. +* Learn about [Selecting Default Databases](../../devops/default-database.md). + \ No newline at end of file From f384a03c840fd7d0b5e280cf569e2e20433908c1 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 6 Oct 2022 14:08:44 -0500 Subject: [PATCH 3/3] ENDOC-534 refining edits --- .../tutorials/create/pb/export-bundle-from-application.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md b/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md index 47cbb79e63..dd3f43a203 100644 --- a/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md +++ b/vuepress/docs/next/tutorials/create/pb/export-bundle-from-application.md @@ -90,11 +90,11 @@ cd YOUR-BUNDLE-NAME ``` 2. Copy the resources from the `testBundle/bundle` directory to the `YOUR-BUNDLE-NAME/platform` directory, with the exception of microservices (/plugins) and micro frontends (/widgets). -For micro frontends and microservices, use the source code to migrate them manually to the corresponding folders inside your bundle directory. Note that non-MFE widgets are considered platform entities on Entando and should be placed in the `platform/widgets` directory. +For micro frontends and microservices, migrate the source code manually to the corresponding folders inside your bundle directory. Note that non-MFE widgets are considered platform entities on Entando and should be placed in the `platform/widgets` directory. Use the [ent bundle CLI tool](../../../docs/getting-started/ent-bundle.md) to assist in the process of adding micro frontends and microservices. To define their specific attributes in the bundle descriptor, `entando.json`, also check out the [Entando Bundle details](../../../docs/curate/bundle-details.md) page. -3. With the project structure in place, [build and publish](publish-project-bundle.md) your bundle. +3. With the project structure in place, [build, publish and install](publish-project-bundle.md) your bundle. ``` ent bundle pack ent bundle publish