Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ENDOC-522 new edits & Engr comments #549

Merged
merged 3 commits into from
Aug 15, 2022
Merged

ENDOC-522 new edits & Engr comments #549

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4987c57
ENDOC-522 new edits & Engr comments
jyunmitch Aug 12, 2022
6c42a44
ENDOC-522 review edits
jyunmitch Aug 15, 2022
fff1d5a
ENDOC-522 more edits
jyunmitch Aug 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 28 additions & 26 deletions vuepress/docs/next/docs/getting-started/ent-bundle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 steps required to create an Entando Bundle.

1. [Initialization](#initialization)
2. [Build](#build)
Expand All @@ -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
| | `rm` | Remove MFE project component
|`ms`|`add`| Add MS project components
| | `init` | Initialize MS 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
jyunmitch marked this conversation as resolved.
Show resolved Hide resolved
|`ent bundle mfe` | `add` | Add an MFE project component
| | `rm` | Remove an MFE project component
|`ent bundle ms`|`add`| Add an MS project component
| | `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
jyunmitch marked this conversation as resolved.
Show resolved Hide resolved
|`ent bundle init [name] --from-hub`| Initialize a bundle from an Entando Hub

#### Command Details
Expand All @@ -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 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
Expand All @@ -76,37 +77,38 @@ 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unless something undocumented changed it's mvn spring:boot run ??

i don't think this is correct. the logs do not print to the text terminal, which is implied by stdout. the logs are redirected to print to the log file, which should be mentioned explicitly.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Engr specifically corrected these in the documentation notes on Google.

Stdout, also known as standard output, is the default file descriptor where a process can write output. In Unix-like operating systems, such as Linux, macOS X, and BSD, stdout is defined by the POSIX standard. Its default file descriptor number is 1. In the terminal, standard output defaults to the user's screen.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Screen Shot 2022-08-15 at 12 40 02 PM

Screen Shot 2022-08-15 at 12 44 41 PM


## 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

first sentence is arranged awkwardly -> "Once the artifacts are generated, Docker images for the microservices are created with the Docker build command using the Dockerfile located in the respective microservice folder."

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

disagree


## 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).

| 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 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|
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

awkward/confusing wording. and can apply to creating bundles for your current project, not just what you do next

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

will when the actual tutorial has a new title so will change with that

14 changes: 11 additions & 3 deletions vuepress/docs/next/docs/getting-started/ent-diag.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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

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"
```
```

### 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.
jyunmitch marked this conversation as resolved.
Show resolved Hide resolved

14 changes: 7 additions & 7 deletions vuepress/docs/next/docs/getting-started/entando-cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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
Expand Down Expand Up @@ -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
```
Expand Down