From 4987c5781f8e30a9bcac2f340c633e444ba99f45 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Fri, 12 Aug 2022 16:17:29 -0500 Subject: [PATCH 1/3] ENDOC-522 new edits & Engr comments --- .../next/docs/getting-started/ent-bundle.md | 52 ++++++++++--------- .../next/docs/getting-started/ent-diag.md | 14 +++-- .../next/docs/getting-started/entando-cli.md | 14 ++--- 3 files changed, 45 insertions(+), 35 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index 48746bdf9c..5183c3a214 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -5,7 +5,7 @@ sidebarDepth: 2 # Bundle Management - ent bundle CLI The Entando Bundle CLI extends the functionality of **ent** with a modular bundle management system. Starting with Entando 7.1, `ent bundle` orchestrates the lifecycle of a project, packaging it into convenient recognizable bundles that can be inserted into any Entando Application. This composable approach takes advantage of a single project descriptor and repository, along with centralized [API management](ent-api.md) and [DB and Keycloak services](ent-svc.md). -This document covers `ent bundle` operations and how it manages a project. +This document covers `ent bundle` operations and the commands required to bundle a project. 1. [Initialization](#initialization) 2. [Build](#build) @@ -27,27 +27,28 @@ The `ent pack` step generates the artifacts and builds the Docker images. A sing See [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-project-bundle.md) for more details. ## ent bundle Command List -syntax: `ent bundle [commands] [subcommand] [options]` | Commands | Subcommands| Description |:-|:-|:---------------------------------- -|`build`||Build components (MFE, MS) with a selector -|`info`||Show status information for the bundle project -|`init`||Initialize project folder structure and descriptor -|`mfe` | `add` | Add an MFE project component -| | `init` | Initialize MFE with scaffolding +|`ent bundle build`||Build components (MFE, MS) with a selector +|`ent bundle generate-cr`||Generate the Entando Custom Resource for a bundle project| +|`ent bundle help` ||Display help for ent bundle +|`ent bundle info`||Show status information for the bundle project +|`ent bundle init`||Initialize project folder structure and descriptor +|`ent bundle list`|| List the available components in the bundle +|`ent bundle mfe` | `add` | Add an MFE project component | | `rm` | Remove MFE project component -|`ms`|`add`| Add MS project components -| | `init` | Initialize MS with scaffolding +|`ent bundle ms`|`add`| Add MS project components | | `rm` | Remove an MS project component -|`run`|| Run bundle components -|`pack`||Create distribution artifacts (Docker images) -|`publish`||Publish images to a Docker registry +|`ent bundle run`|| Run bundle components +|`ent bundle pack`||Create distribution artifacts (Docker images) +|`ent bundle publish`||Publish images to a Docker registry +|`ent --debug bundle`||Enable debug mode| ## Initialization | Command | Description |:--|:-- -|`ent bundle init [name]` |Initialize a new project with the default structure and files +|`ent bundle init [name]` |Initialize a new empty project with the default structure and files |`ent bundle init [name] --from-hub`| Initialize a bundle from an Entando Hub #### Command Details @@ -64,7 +65,7 @@ syntax: `ent bundle [commands] [subcommand] [options]` |`ent bundle build --all-mfe`|Build all the micro frontends| #### Command Details -`ent bundle build`: Constructs the project files based on the `entando.json` provided. It executes according to the type of stack your components are built with. For instance, a React MFE starts an npm build process. A `build` log file is generated for each component inside the .entando/logs directory of your project. +`ent bundle build`: Constructs the project files based on the `entando.json` provided. It executes according to the type of stack your components are built with. For instance, a React MFE starts an npm build process. A `build` log file is generated for each component inside the .entando/logs directory for your project. ## Run | Command| Descriptions @@ -76,26 +77,26 @@ syntax: `ent bundle [commands] [subcommand] [options]` |`ent bundle run --all-mfe`| Locally run the MFEs in the bundle #### Command Details -`ent bundle run`: Executes processes dependent on the component type and stack. For example, mvn spring:boot will execute for a Sping Boot microservice. All the components in the bundle will run in parallel, with a log file generated for each inside the .entando/logs directory. +`ent bundle run`: Executes processes dependent on the component type and stack. For example, `mvn spring-boot:run` will execute for a Spring Boot microservice. All the components in the bundle will run in parallel, with the logs printed to the standard output. ## Package | Command| Descriptions |:--|:-- |`ent bundle pack`|Generate the bundle artifacts, and the bundle and MS images -|`ent bundle pack --org [organization]`|Generate the bundle artifacts, passing the organization name to Docker Hub| +|`ent bundle pack --org [organization]`|Generate the bundle artifacts and images, passing the organization name to Docker Hub| |`ent bundle pack --file [my-dockerfile]`|Use a custom Dockerfile for your bundle | #### Command Details * `ent bundle pack`: The artifacts generated for micro frontends and microservices are stored in their respective folders. Their format depends on the component type. For instance, a React micro frontend may result in HTML, JavaScript and CSS files. -Once the artifacts are generated, Docker images for the microservices are built using the Dockerfile located in each respective folder, with the Docker build command. If the Dockerfile is missing, the `pack` command exits with failure. + Once the artifacts are generated, Docker images for the microservices are built using the Dockerfile located in each respective folder, with the Docker build command. If the Dockerfile is missing, the `pack` command exits with failure. ## Publish | Command| Descriptions |:--|:-- -|ent bundle publish| Publish your Docker images to Docker registry (default) -|ent bundle publish --org [organization]|Publish Docker images to the Docker registry, with a specified organization | -|ent bundle publish --registry [registry]| Publish the Docker images to your Docker registry| +|`ent bundle publish`| Publish your Docker images to a Docker registry (default) +|`ent bundle publish --org [organization]`|Publish Docker images to the Docker registry, with a specified organization | +|`ent bundle publish --registry [registry]`| Publish the Docker images to your Docker registry| ## ECR Commands Entando provides a series of `ent ecr` commands for managing bundle interactions with [the Entando Component Repository](../../docs/compose/ecr-overview.md) (ECR). @@ -103,10 +104,11 @@ Entando provides a series of `ent ecr` commands for managing bundle interactions | Command| Descriptions |:--|:-- |`ent ecr deploy`| Generate the custom resource (CR) and deploy it to the current profile | -|`ent ecr gen-secret`| Generate and display a plugin secret skeleton| +|`ent ecr gen-secret`| Generate and display a plugin Secret skeleton| |`ent ecr generate-cr`|Generate the custom resource | |`ent ecr get-bundle-id [repository-url]` | Calculate and display the bundle ID -|`ent ecr get-plugin-id --auto [repository-url]` | Calculate and display the plugin ID +|`ent ecr get-plugin-code --auto --repo=[repository-url]` |Calculate and display the plugin code for a Git-based v1 bundle| +|`ent ecr get-plugin-code [component-name] --repo=[repository-url]` | Calculate and display the plugin code for a Docker-based v5 bundle |`ent ecr install`| Install a bundle to the ECR| |`ent ecr install --conflict-strategy=OVERRIDE`|Adopt a strategy for conflicts on installed bundles| |`ent ecr list`| Display the list of bundles associated with the current profile| @@ -130,7 +132,7 @@ These ent CLI commands are required when using a Git-based (v1) bundle. |`ent prj ext-keycloak start`|Initialize Keycloak with Docker Compose| |`ent prj fe-test-run`|Initialize one or more frontend widgets, each from its own shell| |`ent prj get-bundle-id --auto`|Determine the project bundle ID| -|`ent prj get-plugin-id --auto --repo=[URL]`|Determine the plugin ID of each microservice in the project| +|`ent prj get-plugin-code --auto [URL]`|Determine the plugin code of each microservice in the project| |`ent prj install`| Install the bundle into Entando| |`ent prj install --conflict-strategy=OVERRIDE`|Adopt a strategy for conflicts on installed bundles |`ent prj pbs-init` | Initialize the bundle directory @@ -139,7 +141,7 @@ These ent CLI commands are required when using a Git-based (v1) bundle. #### Command Details * `ent prj install --conflict-strategy=OVERRIDE`: If a project bundle has already been installed, the `--conflict-strategy` flag forces a `CREATE`, `SKIP`, or `OVERRIDE` strategy for components. -* `ent prj get-bundle-id` and `ent prj get-plugin-id`: Entando uses a unique identifier for a bundle as a way to provide customization parameters and add security controls for bundle-specific resources. A unique identifier is also generated for each microservice plugin in your project. +* `ent prj get-bundle-id` and `ent prj get-plugin-code`: Entando uses a unique identifier for a bundle as a way to provide customization parameters and add security controls for bundle-specific resources. A unique identifier is also generated for each microservice plugin in your project. * `ent bundler`: This provides an interactive mode to identify components to export. Point the bundler to existing environments to extract components and static assets into a custom bundle. This bundle can be used to migrate from one Entando environment to another (e.g. Dev to QA) or as a framework for building a new application. @@ -163,4 +165,4 @@ These ent CLI commands are required when using a Git-based (v1) bundle. ent appname YOUR-APPNAME ent namespace YOUR-NAMESPACE ``` -Check out [Run Blueprint-generated Microservices and Micro Frontends in Dev Mode](../../tutorials/create/ms/run-local.md) for additional information. +Follow the [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-project-bundle.md) tutorial for more details about bundling your next Docker-based project. diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md index b47d186ef7..bc9bc3411f 100644 --- a/vuepress/docs/next/docs/getting-started/ent-diag.md +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -9,12 +9,20 @@ Diagnostic information is critical to analysis and troubleshooting, and the Enta | Command | Description | :- | :- | `ent app-info` | Display basic information about Kubernetes and Entando resources -| `ent pod-info` | Display `kubectl describe` and `kubectl logs` for each Entando pod in a namespace +|`ent bundle info`|Show status information for the bundle project| +|`ent --debug bundle "command"` |Enable debug mode| | `ent diag` | Run diagnostics on the pods currently in an Entando namespace and prepare a diagnostic tar.gz +| `ent pod-info` | Display `kubectl describe` and `kubectl logs` for each Entando pod in a namespace | `ent pod grep --all "error\|fail"` | Locate error messages within EntandoApp pods -The command `ent diag` executes operations to analyze, organize and output detailed pod information. In addition to calling `ent pod-info`, `ent diag` exports custom resources, ingresses, deployments, "previous" pod logs, namespace events, etc. It also generates diagnostics and returns log paths similar to the following: + +### Command Details +* The command `ent diag` executes operations to analyze, organize and output detailed pod information. In addition to calling `ent pod-info`, `ent diag` exports custom resources, ingresses, deployments, "previous" pod logs, namespace events, etc. It also generates diagnostics and returns log paths similar to the following: ``` > Collected diagdata available under "~/.entando/reports/entando-diagdata-2020-11-19T02:58:47+0000" for consultation > Collected diagdata available in archive "~/.entando/reports/entando-diagdata-2020-11-19T02:58:47+0000.tgz" -``` \ No newline at end of file +``` + +### Log Files +* Log files for the bundle build and pack commands are generated for each component inside the .entando/logs directory. For a single component, it is printed to the standard output. Run command logs are also printed to the standard output. + diff --git a/vuepress/docs/next/docs/getting-started/entando-cli.md b/vuepress/docs/next/docs/getting-started/entando-cli.md index 6bd9cb08c2..73a927f303 100644 --- a/vuepress/docs/next/docs/getting-started/entando-cli.md +++ b/vuepress/docs/next/docs/getting-started/entando-cli.md @@ -7,10 +7,10 @@ sidebarDepth: 1 The Entando Command Line Interface, **ent**, provides a set of commands that accelerate common tasks such as installing a new instance of Entando, building projects, creating and deploying bundles, and composing Entando Applications. This document covers the install, command list, and a few operations to start using the ent tool. For specific topics, follow these links: -1. [ent bundle: Project Management](ent-bundle.md) +1. [ent bundle: Bundle Management](ent-bundle.md) 2. [ent api: API Management](ent-api.md) -3. [ent svc: Keycloak and Database Management](ent-svc.md) -4. [ent profile: User Profile Management](ent-profile.md) +3. [ent svc: Services Management](ent-svc.md) +4. [ent profile: Profile Management](ent-profile.md) 5. [ent diag: Diagnostics and Troubleshooting](ent-diag.md) ### Prerequisites @@ -22,8 +22,8 @@ The basic requirements for the CLI vary depending on the type of developer tasks |Basic Development| Git or [Git for Windows](https://gitforwindows.org) | Install Entando in a local VM | [Multipass](https://multipass.run/#install) | Build, Package and Publish Entando Bundles | Docker and Docker Compose -| | a Docker Hub account for Docker images -| Deploy an Entando Bundle | a Kubernetes cluster with admin access or a shared remote cluster +| | A Docker Hub account for Docker images +| Deploy an Entando Bundle | A Kubernetes cluster with admin access or a shared remote cluster >The automatic option in [Getting Started](../getting-started/) will install the CLI along with a quickstart Entando Application. @@ -35,7 +35,7 @@ curl -L https://get.entando.org/cli | bash ## Command List Use `ent help` to review the list of available commands.\ -Use `ent COMMAND --help` to see the details for each command. +Use `ent [command] --help` to see the details for each command. ``` ~~~~~~~~~~~~~~~~~~~ Entando CLI @@ -102,7 +102,7 @@ COMMANDS ``` ### Check the Environment -The `check-env` command checks the dependencies and their versions for your Entando instance, automatically installing them with developer approval. +The `check-env` command checks for dependencies and appropriate versions for your Entando instance, automatically installing them with developer approval. ``` ent check-env develop ``` From 6c42a4439e3c73b88fc645f9a67a94e0f2fe0a62 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Mon, 15 Aug 2022 14:29:19 -0500 Subject: [PATCH 2/3] ENDOC-522 review edits --- .../docs/next/docs/getting-started/ent-bundle.md | 12 ++++++------ vuepress/docs/next/docs/getting-started/ent-diag.md | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index 5183c3a214..03de1c5ef1 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -5,7 +5,7 @@ sidebarDepth: 2 # Bundle Management - ent bundle CLI The Entando Bundle CLI extends the functionality of **ent** with a modular bundle management system. Starting with Entando 7.1, `ent bundle` orchestrates the lifecycle of a project, packaging it into convenient recognizable bundles that can be inserted into any Entando Application. This composable approach takes advantage of a single project descriptor and repository, along with centralized [API management](ent-api.md) and [DB and Keycloak services](ent-svc.md). -This document covers `ent bundle` operations and the commands required to bundle a project. +This document covers `ent bundle` operations and the steps required to create an Entando Bundle. 1. [Initialization](#initialization) 2. [Build](#build) @@ -36,8 +36,8 @@ See [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-proje |`ent bundle init`||Initialize project folder structure and descriptor |`ent bundle list`|| List the available components in the bundle |`ent bundle mfe` | `add` | Add an MFE project component -| | `rm` | Remove MFE project component -|`ent bundle ms`|`add`| Add MS project components +| | `rm` | Remove an MFE project component +|`ent bundle ms`|`add`| Add an MS project component | | `rm` | Remove an MS project component |`ent bundle run`|| Run bundle components |`ent bundle pack`||Create distribution artifacts (Docker images) @@ -65,7 +65,7 @@ See [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-proje |`ent bundle build --all-mfe`|Build all the micro frontends| #### Command Details -`ent bundle build`: Constructs the project files based on the `entando.json` provided. It executes according to the type of stack your components are built with. For instance, a React MFE starts an npm build process. A `build` log file is generated for each component inside the .entando/logs directory for your project. +`ent bundle build`: Constructs the project files based on the provided `entando.json`. It executes according to the type of stack your components are built with. For instance, a React MFE starts an npm build process. A `build` log file is generated for each component inside the .entando/logs directory for your project. ## Run | Command| Descriptions @@ -107,8 +107,8 @@ Entando provides a series of `ent ecr` commands for managing bundle interactions |`ent ecr gen-secret`| Generate and display a plugin Secret skeleton| |`ent ecr generate-cr`|Generate the custom resource | |`ent ecr get-bundle-id [repository-url]` | Calculate and display the bundle ID -|`ent ecr get-plugin-code --auto --repo=[repository-url]` |Calculate and display the plugin code for a Git-based v1 bundle| -|`ent ecr get-plugin-code [component-name] --repo=[repository-url]` | Calculate and display the plugin code for a Docker-based v5 bundle +|`ent ecr get-plugin-code --auto --repo=[repository-url]` |Calculate and display the plugin code for a Git-based bundle| +|`ent ecr get-plugin-code [component-name] --repo=[repository-url]` | Calculate and display the plugin code for a Docker-based bundle |`ent ecr install`| Install a bundle to the ECR| |`ent ecr install --conflict-strategy=OVERRIDE`|Adopt a strategy for conflicts on installed bundles| |`ent ecr list`| Display the list of bundles associated with the current profile| diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md index bc9bc3411f..f7fcec21eb 100644 --- a/vuepress/docs/next/docs/getting-started/ent-diag.md +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -12,7 +12,7 @@ Diagnostic information is critical to analysis and troubleshooting, and the Enta |`ent bundle info`|Show status information for the bundle project| |`ent --debug bundle "command"` |Enable debug mode| | `ent diag` | Run diagnostics on the pods currently in an Entando namespace and prepare a diagnostic tar.gz -| `ent pod-info` | Display `kubectl describe` and `kubectl logs` for each Entando pod in a namespace +| `ent pod-info` | Display the output of `kubectl describe` and `kubectl logs` for each Entando pod in a namespace | `ent pod grep --all "error\|fail"` | Locate error messages within EntandoApp pods @@ -24,5 +24,5 @@ Diagnostic information is critical to analysis and troubleshooting, and the Enta ``` ### Log Files -* Log files for the bundle build and pack commands are generated for each component inside the .entando/logs directory. For a single component, it is printed to the standard output. Run command logs are also printed to the standard output. +* Log files for the bundle build and pack commands are generated for each component inside the .entando/logs directory. For a single component, the log is printed to the stdout. Run command logs are also printed to the standard output. From fff1d5a5cf5e33669ff76ae37c552a33d2b992e7 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Mon, 15 Aug 2022 14:46:10 -0500 Subject: [PATCH 3/3] ENDOC-522 more edits --- vuepress/docs/next/docs/getting-started/ent-diag.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md index f7fcec21eb..936cad0617 100644 --- a/vuepress/docs/next/docs/getting-started/ent-diag.md +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -24,5 +24,4 @@ Diagnostic information is critical to analysis and troubleshooting, and the Enta ``` ### Log Files -* Log files for the bundle build and pack commands are generated for each component inside the .entando/logs directory. For a single component, the log is printed to the stdout. Run command logs are also printed to the standard output. - +* Log files for the `ent bundle build` and `pack` commands are generated for each component inside the .entando/logs directory. For single components and other processes, they are printed to the standard outputs. \ No newline at end of file