From 025cec7ef771d71192583cf12120a89739094bfa Mon Sep 17 00:00:00 2001 From: Lydia Date: Wed, 10 Nov 2021 16:55:49 -0800 Subject: [PATCH 1/7] ENDOC-346 Improve simple bundle tutorial --- .../tutorials/ecr/publish-simple-bundle.md | 83 ++++++++++++------- vuepress/package.json | 4 +- 2 files changed, 55 insertions(+), 32 deletions(-) diff --git a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md index d3d322437c..db1aa1e169 100644 --- a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md @@ -5,32 +5,36 @@ redirectFrom: /next/tutorials/ecr/tutorials/create-ecr-bundle-from-git.html # Build and Publish a Simple Bundle ## Overview -This tutorial shows you how to create a simple Entando bundle and deploy it into the Entando Component Repository. This involves manually defining a bundle with a single widget, checking your bundle artifacts into git, apply the Entando bundle custom resource to Kubernetes, and then installing the bundle into your application. +This tutorial shows how to create a simple Entando bundle and deploy it into the Entando Component Repository. This consists of manually defining a bundle with a single widget, checking the bundle artifacts into Git, applying the Entando bundle custom resource to Kubernetes, and finally installing the bundle into an application. ## Prerequisites -* Use the [Entando CLI](../../docs/reference/entando-cli.md#check-environment) to verify you have the prerequisites in place for this tutorial (e.g. Java, npm, git). +* Use the [Entando CLI](../../docs/reference/entando-cli.md#check-environment) to verify dependencies for this tutorial are installed (e.g. Java, npm, Git) ``` sh ent check-env develop ``` -* You will also need your git credentials, an available git repository, and an Entando instance. +* Git credentials, an empty Git repository and an Entando instance -Some of the following steps can be simplified by using the `ent prj` command and its publication system (pbs) convenience methods. The manual steps are also provided in those cases. +The `ent prj` command and its publication system (pbs) convenience methods consolidate multiple commands into single entries. Both the simplified and uncondensed sets of commands are provided. ## Create the project structure -First create a parent project directory along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files also live under the parent directory. +First create a parent project directory (e.g. `example-bundle` along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files live under the parent directory. ``` sh mkdir -p example-bundle/bundle; cd example-bundle/bundle ``` ## Add a simple widget -Create a widget directory and descriptor file: +Create a widget directory: ``` sh mkdir widgets +``` + +Create a widget descriptor file within that directory: +``` sh touch widgets/example-widget.yaml ``` -Populate the `example-widget.yaml` with a simple definition. Make sure to retain the correct YAML indentation. +Populate the widget descriptor file `example-widget.yaml` with a simple definition. Make sure to retain the correct YAML indentation of 2 or 4 spaces. ``` yaml code: example-widget titles: @@ -42,12 +46,12 @@ customUi:

Hi from Example Widget

## Create the bundle descriptor -The `descriptor.yaml` is the main file processed by the Entando Component Repository and describes all of the components in the bundle. The name of the bundle descriptor must be `descriptor.yaml`. +The bundle descriptor file `descriptor.yaml` is the main file processed by the Entando Component Repository and describes all of the components within the bundle. The name of the bundle descriptor must be `descriptor.yaml` and it must be stored in the child bundle directory (e.g. `example-bundle/bundle`). ```sh touch descriptor.yaml ``` -Populate the descriptor with the following YAML definition: +Populate the bundle descriptor file with the following YAML definition: ``` yaml code: example-bundle description: This is an example of an Entando bundle @@ -55,68 +59,74 @@ components: widgets: - widgets/example-widget.yaml ``` -The component descriptor file name and location (e.g. `widgets/example-widget.yaml`) are arbitrary since the bundle descriptor explicitly points to the file. The typical convention is to group components by type, for example with all widgets in one directory, all page templates in another, etc. +Component descriptor file names and locations (e.g. `widgets/example-widget.yaml`) are arbitrary since the bundle descriptor explicitly points to those files. Convention is to group components by type (e.g. all widgets in one directory, all page templates in another, etc.). ## Publish the bundle -You can publish a bundle using the CLI or you can perform the steps by hand. +The bundle can be published using the `ent prj` command or the equivalent steps can be performed manually. -### CLI steps +### CLI steps with `ent prj` 1. Change to the project directory, if needed ```sh cd example-bundle ``` -2. Initialize the Entando project and accept the defaults. +2. Initialize the Entando project and accept the defaults ``` sh ent prj init ``` -3. Initialize the publication system. You'll need the git repository URL and your credentials here. + +3. Initialize the publication system. This step requires the empty Git repository URL (ending in .git) and your credentials. ``` sh ent prj pbs-init ``` -4. Publish the bundle to git. By convention your first version will be `v0.0.1` but this is up to you. + +4. Publish the bundle to Git. By convention the first version will be `v0.0.1` but this tag can be modified. ``` sh ent prj pbs-publish ``` -On subsequent iterations you can run just this command again to quickly push a new version of your bundle to git. +Upon subsequent iterations just this command can be run again to quickly push a new version of the bundle to Git. -5. You can now deploy the bundle into the Entando Component Repository in one step. +5. The bundle can now be deployed into the Entando Component Repository in one step ``` sh ent prj deploy ``` - The `prj deploy` command uses the git repository URL and project name from earlier steps to create the custom resource. + The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) from earlier steps to create the custom resource. -6. Jump to the section below to finish installing your bundle: [Install the bundle into an application](#install-the-bundle-into-an-application) +6. Jump to [Install the bundle into an application](#install-the-bundle-into-an-application) to finish installing your bundle. -### Manual steps -1. Change to the bundle directory, if needed +### Unsimplified CLI steps +1. Change to the bundle directory if needed ``` sh cd example-bundle/bundle ``` -2. Run the following commands to initialize git and commit the files. +2. Run the following commands to initialize Git and commit the files ``` sh git init git add . git commit -m "Init Git repository" ``` -3. Add your remote repository as origin and push the bundle. +3. Add your remote repository as origin and push the bundle ``` sh git remote add origin https://your/remote/repository.git git push -u origin master ``` +Note: To update the URL of the remote repository with the name “origin” to the URL of the remote repository you want to add use the following command: +``` sh +git remote set-url origin https://your/remote/repository.git +``` -4. Publish a git tag using the following commands. +4. Publish a Git tag with the following commands ``` sh git tag -a "v0.0.1" -m "My first tag" git push --tags ``` -5. Now that you've published your bundle to git you can create the Kubernetes custom resource for it. +5. Now that you've published your bundle to Git you can create the Kubernetes custom resource for it. -Install the bundler if you haven't previously done so. +Install the bundler if you haven't previously done so ``` sh npm install -g @entando/entando-bundler@6.3.2 ``` @@ -124,18 +134,29 @@ npm install -g @entando/entando-bundler@6.3.2 Next generate the custom resource for your bundle. Run the `entando-bundler from-git` command and provide your remote git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also provide a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. ``` sh -entando-bundler from-git --name=example-bundle --namespace=entandp --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml +entando-bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml ``` -Next you can apply this definition to Kubernetes. You may need to first transfer the file to your VM, e.g using `multipass transfer`. +Now you can apply this definition to Kubernetes. You may need to first transfer the file to your VM (e.g by mounting the project directory). ``` kubectl -n entando apply -f example-bundle.yaml ``` -You can confirm the presence of your custom resource via `kubectl get EntandoDeBundle -n entando` +If you encounter the error +``` +Unable to read /etc/rancher/k3s/k3s.yaml, please start server with — write-kubeconfig-mode to modify kube config permissions + +error: Error loading config file “/etc/rancher/k3s/k3s.yaml”: open /etc/rancher/k3s/k3s.yaml: permission denied +``` +send the following command +``` +sudo chmod -R 777 /etc/rancher/k3s/k3s.yaml +``` + +You can confirm the presence of your custom resource via `kubectl get EntandoDeBundle -n entando`. ## Install the bundle into an application -Now you can go to the `App Builder` → `Component Repository` and install your bundle. You should see your bundle in the list and when you click `Install` you can select your preferred version if the bundle contains more than one. +Now you can go to the `App Builder` → `Component Repository` and install your bundle. You should see your bundle listed; clicking `Install` you should be able to select your preferred version if the bundle contains more than one. -At this point the Entando platform will download and install the components contained in the bundle. Once complete you should see the `Install` button change to give you an option to `Uninstall` that specific version. You can also navigate to `Components` → `Micro Frontends & Widgets` and find your custom widget under the `User` section. +The Entando platform will download and install the components contained in the bundle. Once complete you should see the `Install` button change to give you the option to `Uninstall` that specific version. If you navigate to `Components` → `Micro Frontends & Widgets` should should find your custom widget under the `User` section. diff --git a/vuepress/package.json b/vuepress/package.json index 07ef37e2c2..b87522d465 100644 --- a/vuepress/package.json +++ b/vuepress/package.json @@ -55,5 +55,7 @@ "> 1%", "last 2 versions", "not dead" - ] + ], + "main": "index.js", + "license": "MIT" } From 1044413e97c9953b13ab50aa7784b9874dc74e51 Mon Sep 17 00:00:00 2001 From: Lydia Date: Wed, 10 Nov 2021 21:00:05 -0800 Subject: [PATCH 2/7] ENDOC-346 Fix syntax and clarify instructions --- .../tutorials/ecr/publish-simple-bundle.md | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md index db1aa1e169..70c1b12be9 100644 --- a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md @@ -5,16 +5,16 @@ redirectFrom: /next/tutorials/ecr/tutorials/create-ecr-bundle-from-git.html # Build and Publish a Simple Bundle ## Overview -This tutorial shows how to create a simple Entando bundle and deploy it into the Entando Component Repository. This consists of manually defining a bundle with a single widget, checking the bundle artifacts into Git, applying the Entando bundle custom resource to Kubernetes, and finally installing the bundle into an application. +In this tutorial you will learn how to create a simple Entando bundle and deploy it into the Entando Component Repository. This involves manually defining a bundle with a single widget, checking the bundle artifacts into Git, applying the Entando bundle custom resource to Kubernetes, and then installing the bundle into an application. ## Prerequisites -* Use the [Entando CLI](../../docs/reference/entando-cli.md#check-environment) to verify dependencies for this tutorial are installed (e.g. Java, npm, Git) +* Use the [Entando CLI](../../docs/reference/entando-cli.md#check-environment) to verify all dependencies for this tutorial are installed (e.g. Java, npm, Git). ``` sh ent check-env develop ``` -* Git credentials, an empty Git repository and an Entando instance +* Authenticated Git credentials, an empty Git repository and an available Entando instance are required for the commands below to execute without errors. -The `ent prj` command and its publication system (pbs) convenience methods consolidate multiple commands into single entries. Both the simplified and uncondensed sets of commands are provided. +The `ent prj` command and its publication system (pbs) convenience methods consolidate multiple steps into a single command. Both the simplified and uncondensed sets of commands are provided. ## Create the project structure First create a parent project directory (e.g. `example-bundle` along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files live under the parent directory. @@ -24,12 +24,12 @@ mkdir -p example-bundle/bundle; cd example-bundle/bundle ``` ## Add a simple widget -Create a widget directory: +Create a widget directory ``` sh mkdir widgets ``` -Create a widget descriptor file within that directory: +Create a widget descriptor file within that directory ``` sh touch widgets/example-widget.yaml ``` @@ -51,7 +51,7 @@ The bundle descriptor file `descriptor.yaml` is the main file processed by the E touch descriptor.yaml ``` -Populate the bundle descriptor file with the following YAML definition: +Populate the bundle descriptor file with the following YAML definition ``` yaml code: example-bundle description: This is an example of an Entando bundle @@ -63,10 +63,10 @@ Component descriptor file names and locations (e.g. `widgets/example-widget.yaml ## Publish the bundle -The bundle can be published using the `ent prj` command or the equivalent steps can be performed manually. +The bundle can be published using the `ent prj` command, or the equivalent steps can be performed manually. ### CLI steps with `ent prj` -1. Change to the project directory, if needed +1. Change to the project directory if needed ```sh cd example-bundle ``` @@ -81,17 +81,17 @@ ent prj init ent prj pbs-init ``` -4. Publish the bundle to Git. By convention the first version will be `v0.0.1` but this tag can be modified. +4. Publish the bundle to Git. By convention the first version is assigned the tag `v0.0.1`. This tag can be modified to use your preferred versioning format. ``` sh ent prj pbs-publish ``` -Upon subsequent iterations just this command can be run again to quickly push a new version of the bundle to Git. +Running just the command `ent prj pbs-publish` will quickly push subsequent iterations of the bundle to Git. You will be asked to input the bundle version each time. To ensure that iterations are listed in the correct order you must be consistent with versioning format and alphanumeric precedence. -5. The bundle can now be deployed into the Entando Component Repository in one step +5. The bundle can now be deployed into the Entando Component Repository with one command ``` sh ent prj deploy ``` - The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) from earlier steps to create the custom resource. + The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) to create the custom resource. 6. Jump to [Install the bundle into an application](#install-the-bundle-into-an-application) to finish installing your bundle. @@ -113,12 +113,12 @@ git commit -m "Init Git repository" git remote add origin https://your/remote/repository.git git push -u origin master ``` -Note: To update the URL of the remote repository with the name “origin” to the URL of the remote repository you want to add use the following command: +Note: To update the URL of the remote repository with the name “origin” to the URL of the remote repository you want to add use ``` sh git remote set-url origin https://your/remote/repository.git ``` -4. Publish a Git tag with the following commands +4. Publish a Git tag ``` sh git tag -a "v0.0.1" -m "My first tag" git push --tags @@ -131,7 +131,7 @@ Install the bundler if you haven't previously done so npm install -g @entando/entando-bundler@6.3.2 ``` -Next generate the custom resource for your bundle. Run the `entando-bundler from-git` command and provide your remote git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also provide a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. +To generate the custom resource for your bundle run the `entando-bundler from-git` command, then provide your remote git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also provide a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. ``` sh entando-bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml @@ -154,9 +154,9 @@ send the following command sudo chmod -R 777 /etc/rancher/k3s/k3s.yaml ``` -You can confirm the presence of your custom resource via `kubectl get EntandoDeBundle -n entando`. +You can confirm the presence of your custom resource with the command `kubectl get EntandoDeBundle -n entando`. ## Install the bundle into an application -Now you can go to the `App Builder` → `Component Repository` and install your bundle. You should see your bundle listed; clicking `Install` you should be able to select your preferred version if the bundle contains more than one. +Your bundle should appear in `App Builder` → `Component Repository` in your Entando instance. Clicking `Install` should allow version selection if your bundle has multiple iterations. -The Entando platform will download and install the components contained in the bundle. Once complete you should see the `Install` button change to give you the option to `Uninstall` that specific version. If you navigate to `Components` → `Micro Frontends & Widgets` should should find your custom widget under the `User` section. +The Entando platform will then download and install the components contained in the bundle. Once complete you should see the `Install` button change to give you the option to `Uninstall` that specific version. If you navigate to `Components` → `Micro Frontends & Widgets` you should find your custom widget within the `User` section. From c6974468341d52be6dedd2ad5d447f4a425b9a0f Mon Sep 17 00:00:00 2001 From: Lydia Date: Thu, 11 Nov 2021 09:26:16 -0800 Subject: [PATCH 3/7] ENDOC-346 Fix CLI vs manual + nitpicking --- .../v6.3.2/tutorials/ecr/publish-simple-bundle.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md index 70c1b12be9..7616c60c8c 100644 --- a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md @@ -14,7 +14,7 @@ ent check-env develop ``` * Authenticated Git credentials, an empty Git repository and an available Entando instance are required for the commands below to execute without errors. -The `ent prj` command and its publication system (pbs) convenience methods consolidate multiple steps into a single command. Both the simplified and uncondensed sets of commands are provided. +Publishing a bundle can be simplified by using the `ent prj` command and its publication system (pbs) convenience methods. Both the CLI and manual commands are provided. ## Create the project structure First create a parent project directory (e.g. `example-bundle` along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files live under the parent directory. @@ -63,9 +63,9 @@ Component descriptor file names and locations (e.g. `widgets/example-widget.yaml ## Publish the bundle -The bundle can be published using the `ent prj` command, or the equivalent steps can be performed manually. +The bundle can be published using the CLI or the steps can be performed manually. -### CLI steps with `ent prj` +### CLI steps 1. Change to the project directory if needed ```sh cd example-bundle @@ -76,7 +76,7 @@ cd example-bundle ent prj init ``` -3. Initialize the publication system. This step requires the empty Git repository URL (ending in .git) and your credentials. +3. Initialize the publication system. This step requires the empty Git repository URL (ending in .git) and your Git credentials. ``` sh ent prj pbs-init ``` @@ -95,7 +95,7 @@ ent prj deploy 6. Jump to [Install the bundle into an application](#install-the-bundle-into-an-application) to finish installing your bundle. -### Unsimplified CLI steps +### Manual steps 1. Change to the bundle directory if needed ``` sh cd example-bundle/bundle @@ -113,7 +113,7 @@ git commit -m "Init Git repository" git remote add origin https://your/remote/repository.git git push -u origin master ``` -Note: To update the URL of the remote repository with the name “origin” to the URL of the remote repository you want to add use +Note: To update the URL of an existing remote repository named “origin” to the remote repository you want to add use ``` sh git remote set-url origin https://your/remote/repository.git ``` @@ -131,7 +131,7 @@ Install the bundler if you haven't previously done so npm install -g @entando/entando-bundler@6.3.2 ``` -To generate the custom resource for your bundle run the `entando-bundler from-git` command, then provide your remote git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also provide a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. +To generate the custom resource for your bundle run the `entando-bundler from-git` command, then provide your remote Git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also provide a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. ``` sh entando-bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml From a0e13b7596a0a52999f990e2cca3cc95abb48fa1 Mon Sep 17 00:00:00 2001 From: Lydia Date: Thu, 11 Nov 2021 11:52:08 -0800 Subject: [PATCH 4/7] EDOC-346 Cite `multipass transfer` --- vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md index 7616c60c8c..3f2f86d1b3 100644 --- a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md @@ -137,7 +137,7 @@ To generate the custom resource for your bundle run the `entando-bundler from-gi entando-bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml ``` -Now you can apply this definition to Kubernetes. You may need to first transfer the file to your VM (e.g by mounting the project directory). +Now you can apply this definition to Kubernetes. You may need to first transfer the file to your VM, e.g using `multipass transfer`. ``` kubectl -n entando apply -f example-bundle.yaml From 50295b8bf431ddb44d8d64834fec382697ae63da Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 12 Nov 2021 09:05:55 -0800 Subject: [PATCH 5/7] ENDOC-346 Remove troubleshooting --- .../tutorials/ecr/publish-simple-bundle.md | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md index 3f2f86d1b3..4d6cae2bd1 100644 --- a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md @@ -113,10 +113,6 @@ git commit -m "Init Git repository" git remote add origin https://your/remote/repository.git git push -u origin master ``` -Note: To update the URL of an existing remote repository named “origin” to the remote repository you want to add use -``` sh -git remote set-url origin https://your/remote/repository.git -``` 4. Publish a Git tag ``` sh @@ -137,23 +133,12 @@ To generate the custom resource for your bundle run the `entando-bundler from-gi entando-bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml ``` -Now you can apply this definition to Kubernetes. You may need to first transfer the file to your VM, e.g using `multipass transfer`. +Now you can apply this definition to Kubernetes. You may need to first transfer the file to your VM (e.g using `multipass transfer`). ``` kubectl -n entando apply -f example-bundle.yaml ``` -If you encounter the error -``` -Unable to read /etc/rancher/k3s/k3s.yaml, please start server with — write-kubeconfig-mode to modify kube config permissions - -error: Error loading config file “/etc/rancher/k3s/k3s.yaml”: open /etc/rancher/k3s/k3s.yaml: permission denied -``` -send the following command -``` -sudo chmod -R 777 /etc/rancher/k3s/k3s.yaml -``` - You can confirm the presence of your custom resource with the command `kubectl get EntandoDeBundle -n entando`. ## Install the bundle into an application From 8309127c4140465cb06e6aed921282cba65ffe4e Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 12 Nov 2021 11:10:16 -0800 Subject: [PATCH 6/7] ENDOC-346 Fine-tuning --- vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md index 4d6cae2bd1..3a7f84091f 100644 --- a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md @@ -81,7 +81,7 @@ ent prj init ent prj pbs-init ``` -4. Publish the bundle to Git. By convention the first version is assigned the tag `v0.0.1`. This tag can be modified to use your preferred versioning format. +4. Publish the bundle to Git. By convention the first version is assigned the tag `v0.0.1` but the prefix "v" is optional. ``` sh ent prj pbs-publish ``` From e79088d366d61c50f8c67903c2fd00b0cf81ffd4 Mon Sep 17 00:00:00 2001 From: Lydia Date: Fri, 12 Nov 2021 13:13:11 -0800 Subject: [PATCH 7/7] ENDOC-346 Absorb review comments, copy to Next --- .../tutorials/ecr/publish-simple-bundle.md | 70 ++++++++++--------- .../tutorials/ecr/publish-simple-bundle.md | 6 +- 2 files changed, 41 insertions(+), 35 deletions(-) diff --git a/vuepress/docs/next/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/next/tutorials/ecr/publish-simple-bundle.md index d3d322437c..cc33730907 100644 --- a/vuepress/docs/next/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/ecr/publish-simple-bundle.md @@ -5,32 +5,36 @@ redirectFrom: /next/tutorials/ecr/tutorials/create-ecr-bundle-from-git.html # Build and Publish a Simple Bundle ## Overview -This tutorial shows you how to create a simple Entando bundle and deploy it into the Entando Component Repository. This involves manually defining a bundle with a single widget, checking your bundle artifacts into git, apply the Entando bundle custom resource to Kubernetes, and then installing the bundle into your application. +In this tutorial you will learn how to create a simple Entando bundle and deploy it into the Entando Component Repository. This involves manually defining a bundle with a single widget, checking the bundle artifacts into Git, applying the Entando bundle custom resource to Kubernetes, and then installing the bundle into an application. ## Prerequisites -* Use the [Entando CLI](../../docs/reference/entando-cli.md#check-environment) to verify you have the prerequisites in place for this tutorial (e.g. Java, npm, git). +* Use the [Entando CLI](../../docs/reference/entando-cli.md#check-environment) to verify all dependencies for this tutorial are installed (e.g. Java, npm, Git). ``` sh ent check-env develop ``` -* You will also need your git credentials, an available git repository, and an Entando instance. +* Authenticated Git credentials, an empty Git repository and an available Entando instance are required for the commands below to execute without errors. -Some of the following steps can be simplified by using the `ent prj` command and its publication system (pbs) convenience methods. The manual steps are also provided in those cases. +Publishing a bundle can be simplified by using the `ent prj` command and its publication system (pbs) convenience methods. Both the CLI and manual commands are provided. ## Create the project structure -First create a parent project directory along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files also live under the parent directory. +First create a parent project directory (e.g. `example-bundle`) along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files live under the parent directory. ``` sh mkdir -p example-bundle/bundle; cd example-bundle/bundle ``` ## Add a simple widget -Create a widget directory and descriptor file: +Create a widget directory ``` sh mkdir widgets +``` + +Create a widget descriptor file within that directory +``` sh touch widgets/example-widget.yaml ``` -Populate the `example-widget.yaml` with a simple definition. Make sure to retain the correct YAML indentation. +Populate the widget descriptor file `example-widget.yaml` with a simple definition. Make sure to retain the correct YAML indentation of 2 or 4 spaces. ``` yaml code: example-widget titles: @@ -42,12 +46,12 @@ customUi:

Hi from Example Widget

## Create the bundle descriptor -The `descriptor.yaml` is the main file processed by the Entando Component Repository and describes all of the components in the bundle. The name of the bundle descriptor must be `descriptor.yaml`. +The main file processed by the Entando Component Repository is `descriptor.yaml`, which describes all of the components within the bundle. The name of the bundle descriptor file must be `descriptor.yaml` and it must be stored in the child bundle directory (e.g. `example-bundle/bundle`). ```sh touch descriptor.yaml ``` -Populate the descriptor with the following YAML definition: +Populate the bundle descriptor file with the following YAML definition ``` yaml code: example-bundle description: This is an example of an Entando bundle @@ -55,87 +59,89 @@ components: widgets: - widgets/example-widget.yaml ``` -The component descriptor file name and location (e.g. `widgets/example-widget.yaml`) are arbitrary since the bundle descriptor explicitly points to the file. The typical convention is to group components by type, for example with all widgets in one directory, all page templates in another, etc. +Component descriptor file names and locations (e.g. `widgets/example-widget.yaml`) are arbitrary since the bundle descriptor explicitly points to those files. Convention is to group components by type with all widgets in one directory, all page templates in another, etc. ## Publish the bundle -You can publish a bundle using the CLI or you can perform the steps by hand. +The bundle can be published using the CLI or the steps can be performed manually. ### CLI steps -1. Change to the project directory, if needed +1. Change to the project directory if needed ```sh cd example-bundle ``` -2. Initialize the Entando project and accept the defaults. +2. Initialize the Entando project and accept the defaults ``` sh ent prj init ``` -3. Initialize the publication system. You'll need the git repository URL and your credentials here. + +3. Initialize the publication system. This step requires the empty Git repository URL (ending in .git) and your Git credentials. ``` sh ent prj pbs-init ``` -4. Publish the bundle to git. By convention your first version will be `v0.0.1` but this is up to you. + +4. Publish the bundle to Git. By convention the first version is assigned the tag `v0.0.1` but the prefix "v" is optional. ``` sh ent prj pbs-publish ``` -On subsequent iterations you can run just this command again to quickly push a new version of your bundle to git. +Running just the command `ent prj pbs-publish` will quickly push subsequent iterations of the bundle to Git. You will be asked to input the bundle version each time. To ensure that iterations are listed in the correct order you must be consistent with versioning format and alphanumeric precedence. -5. You can now deploy the bundle into the Entando Component Repository in one step. +5. The bundle can now be deployed into the Entando Component Repository with one command ``` sh ent prj deploy ``` - The `prj deploy` command uses the git repository URL and project name from earlier steps to create the custom resource. + The `prj deploy` command uses the Git repository URL and project name (e.g. `example-bundle`) to create the custom resource. -6. Jump to the section below to finish installing your bundle: [Install the bundle into an application](#install-the-bundle-into-an-application) +6. Jump to [Install the bundle into an application](#install-the-bundle-into-an-application) to finish installing your bundle. -### Manual steps -1. Change to the bundle directory, if needed +### Manual steps +1. Change to the bundle directory if needed ``` sh cd example-bundle/bundle ``` -2. Run the following commands to initialize git and commit the files. +2. Run the following commands to initialize Git and commit the files ``` sh git init git add . git commit -m "Init Git repository" ``` -3. Add your remote repository as origin and push the bundle. +3. Add your remote repository as origin and push the bundle ``` sh git remote add origin https://your/remote/repository.git git push -u origin master ``` -4. Publish a git tag using the following commands. +4. Publish a Git tag ``` sh git tag -a "v0.0.1" -m "My first tag" git push --tags ``` -5. Now that you've published your bundle to git you can create the Kubernetes custom resource for it. +5. Now that you've published your bundle to Git you can create the Kubernetes custom resource for it. -Install the bundler if you haven't previously done so. +Install the bundler if you haven't previously done so ``` sh npm install -g @entando/entando-bundler@6.3.2 ``` -Next generate the custom resource for your bundle. Run the `entando-bundler from-git` command and provide your remote git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also provide a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. +To generate the custom resource for your bundle run the `entando-bundler from-git` command, then provide your remote Git repository URL via the `--repository` option and the correct namespace via `--namespace`. You can also provide a thumbnail for your bundle with `--thumbnail-file` or `--thumbnail-url`. ``` sh -entando-bundler from-git --name=example-bundle --namespace=entandp --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml +entando-bundler from-git --name=example-bundle --namespace=entando --repository=https://your/remote/repository.git --dry-run > example-bundle.yaml ``` -Next you can apply this definition to Kubernetes. You may need to first transfer the file to your VM, e.g using `multipass transfer`. +Now you can apply this definition to Kubernetes. You may need to first transfer the file to your VM (e.g using `multipass transfer`). ``` kubectl -n entando apply -f example-bundle.yaml ``` -You can confirm the presence of your custom resource via `kubectl get EntandoDeBundle -n entando` +You can confirm the presence of your custom resource with the command `kubectl get EntandoDeBundle -n entando`. ## Install the bundle into an application -Now you can go to the `App Builder` → `Component Repository` and install your bundle. You should see your bundle in the list and when you click `Install` you can select your preferred version if the bundle contains more than one. +Your bundle should appear in `App Builder` → `Component Repository` in your Entando instance. Clicking `Install` should allow version selection if your bundle has multiple iterations. -At this point the Entando platform will download and install the components contained in the bundle. Once complete you should see the `Install` button change to give you an option to `Uninstall` that specific version. You can also navigate to `Components` → `Micro Frontends & Widgets` and find your custom widget under the `User` section. +The Entando platform will then download and install the components contained in the bundle. Once complete you should see the `Install` button change to give you the option to `Uninstall` that specific version. If you navigate to `Components` → `Micro Frontends & Widgets` you should find your custom widget within the `User` section. diff --git a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md index 3a7f84091f..cc33730907 100644 --- a/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md +++ b/vuepress/docs/v6.3.2/tutorials/ecr/publish-simple-bundle.md @@ -17,7 +17,7 @@ ent check-env develop Publishing a bundle can be simplified by using the `ent prj` command and its publication system (pbs) convenience methods. Both the CLI and manual commands are provided. ## Create the project structure -First create a parent project directory (e.g. `example-bundle` along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files live under the parent directory. +First create a parent project directory (e.g. `example-bundle`) along with a child bundle directory. In a project generated by the Entando Component Generator the microservice and micro frontend source files live under the parent directory. ``` sh mkdir -p example-bundle/bundle; cd example-bundle/bundle @@ -46,7 +46,7 @@ customUi:

Hi from Example Widget

## Create the bundle descriptor -The bundle descriptor file `descriptor.yaml` is the main file processed by the Entando Component Repository and describes all of the components within the bundle. The name of the bundle descriptor must be `descriptor.yaml` and it must be stored in the child bundle directory (e.g. `example-bundle/bundle`). +The main file processed by the Entando Component Repository is `descriptor.yaml`, which describes all of the components within the bundle. The name of the bundle descriptor file must be `descriptor.yaml` and it must be stored in the child bundle directory (e.g. `example-bundle/bundle`). ```sh touch descriptor.yaml ``` @@ -59,7 +59,7 @@ components: widgets: - widgets/example-widget.yaml ``` -Component descriptor file names and locations (e.g. `widgets/example-widget.yaml`) are arbitrary since the bundle descriptor explicitly points to those files. Convention is to group components by type (e.g. all widgets in one directory, all page templates in another, etc.). +Component descriptor file names and locations (e.g. `widgets/example-widget.yaml`) are arbitrary since the bundle descriptor explicitly points to those files. Convention is to group components by type with all widgets in one directory, all page templates in another, etc. ## Publish the bundle