From 7a1a764b2fc0cb80e837037e7c484a515220263a Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Tue, 19 Jul 2022 14:03:13 -0500 Subject: [PATCH 01/34] ENDOC-522 ent-cli reorg basics and nav --- vuepress/docs/.vuepress/next.js | 31 ++ .../next/docs/getting-started/entando-cli.md | 154 +++++++ .../docs/next/docs/reference/entando-cli.md | 400 ------------------ 3 files changed, 185 insertions(+), 400 deletions(-) create mode 100644 vuepress/docs/next/docs/getting-started/entando-cli.md delete mode 100644 vuepress/docs/next/docs/reference/entando-cli.md diff --git a/vuepress/docs/.vuepress/next.js b/vuepress/docs/.vuepress/next.js index 0b88fc847f..eb50c60754 100644 --- a/vuepress/docs/.vuepress/next.js +++ b/vuepress/docs/.vuepress/next.js @@ -20,6 +20,37 @@ module.exports = { title: 'Entando Architecture', path: path + 'getting-started/concepts-overview.md', }, + { + title: 'Entando CLI', + children: [ + { + title: 'Basics', + path: path + 'getting-started/entando-cli.md', + }, + { + title: 'ent Bundle Management', + path: path + 'getting-started/ent-bundle.md', + }, + { + title: 'ent API Management', + path: path + 'getting-started/ent-api.md', + }, + { + title: 'ent Services Management', + path: path + 'getting-started/ent-svc.md', + }, + { + title: 'ent Profile Management', + path: path + 'getting-started/ent-profile.md', + }, + { + title: 'ent Diagnostics and Troubleshooting', + path: path + 'getting-started/ent-diag.md', + } + ] + + } + ] }, { diff --git a/vuepress/docs/next/docs/getting-started/entando-cli.md b/vuepress/docs/next/docs/getting-started/entando-cli.md new file mode 100644 index 0000000000..63a6274681 --- /dev/null +++ b/vuepress/docs/next/docs/getting-started/entando-cli.md @@ -0,0 +1,154 @@ +--- +sidebarDepth: 1 +--- + +# Entando CLI + +The Entando Command Line Interface (CLI) tool--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 overview covers the basic install, set-up, and command list for the ent tool. + +For specific topics, follow these links: +1. [ent bundle: Project 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) +5. [ent diag: Diagnostics and Troubleshooting](ent-diag.md) + +### Prerequisites + +The basic requirements for the CLI vary depending on the type of developer tasks as shown here. Ent is able to install secondary dependencies using the `ent check-env` command as described [here](#check-the-environment). + +| Category | Prerequisite +| :- | :- +|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 (or organization) Docker images +| Deploy an Entando Bundle | a Kubernetes cluster with admin access or a shared remote cluster + +>TIP +>The automatic option in [Getting Started](../getting-started/) will install the CLI along with an Ubuntu VM containing K3s Kubernetes and a quickstart Entando Application. + + +## Install the CLI +Install the current offical release of the CLI with the following command: +``` bash +curl -L https://get.entando.org/cli | bash +``` + +## Commands Overview +Use `ent help` to review the list of available commands. + +``` +~~~~~~~~~~~~~~~~~~~ + Entando CLI +~~~~~~~~~~~~~~~~~~~ + +> Essentials: + - Activate using: ~/.entando/ent/v7.0.0/cli/v7.0.0/activate + - Deactivate using: ~/.entando/ent/v7.0.0/cli/v7.0.0/deactivate +> Syntax: +ent [command] [subcommand] [name] [flags] + +> ent Commands: + - app => Helper for managing an Entando App + - app-info => Displays information about an Entando App + - bundle => Helper for managing bundle functions. See below for more details + - check-env => Checks the environment for required dependencies and settings + - diag => Runs diagnostics and aggregates the related info in a .tgz file + - ent => Helper for managing the local ent installations + - ecr => Helper for managing the ECR + - help => Help information + - host => Helper for managing the system that hosts the quickstart VM + - jhipster (not there) + - kubectl => Helper for using kubectl in ent managed scenarios + - node-cmd-wrapper => wrapper of node commands + - pod => Displays information related to a set of pods + - prj => Helper for managing Entando bundle projects + - profile => Helper for managing an Entando App + - quickstart => Helper for installing Entando instances locally + - run-tests => Runs the internal tests +> Further info about entando: + - ~/.entando/ent/v7.0.0/cli/v7.0.0/README.md + - https://www.entando.com/ + - https://developer.entando.com/ + +> ⚠ RECOMMENDED FIRST STEP ⚠ : + - Check the dependencies (ent check-env --help) +``` +``` +~~~~~~~~~~~~~~~~~~~ + ent bundle CLI +~~~~~~~~~~~~~~~~~~~ +VERSION + @entando/entando-bundle-cli/0.0.1-ENG-3939-PR-101 darwin-x64 node-v14.19.0 + +USAGE + $ ent bundle [COMMAND] + +TOPICS + api Manage API claims + mfe Micro Frontend operations + ms Microservice operations + svc Manage auxiliary services + +COMMANDS + build Build bundle components + generate-cr Generate the Entando Custom Resource (CR) for a bundle project + help Display help for ent bundle. + info Show status information for the bundle project + init Perform the scaffolding of a bundle project + list List the available components in the bundle + pack Generate the bundle Docker images + publish Publish bundle Docker images + run Run bundle components + +``` + + +### Check the Environment + +Use the `check-env` command to prepare your environment for development. This will verify the presence of required dependencies as well as the appropriate versions for your specific Entando instance. Typically, it will automatically install dependencies and prompt the developer for guidance or approval as needed. +``` bash +ent check-env develop +``` +>Check a command's help text (`--help`) to view specific options and subcommands, e.g. `ent check-env --help`. + +### Update the CLI +To update ent to the latest version: + +``` sh +bash <(curl -L "https://get.entando.org/cli") --update +``` + +Run `ent check-env develop` after updating to determine if dependency versions have changed. + +Alternatively, deleting the `~/.entando` directory with `rm -rf ~/.entando` and then reinstalling the CLI, per the instructions above, will perform a clean install. This will also remove the private copies of JHipster, Entando Blueprint, etc. + +### Customize Quickstart +The `ent quickstart` command supports parameters to customize your quickstart environment. These options allow you to modify specific properties of your VM, installation versions and databases. + +For example, to reuse an existing VM: +``` sh +ent quickstart --vm-reuse=YOUR-EXISTING-VM +``` +For additional information, check the output of +``` sh +ent quickstart --help +``` + + + +### Reference +* Source repository: \ No newline at end of file diff --git a/vuepress/docs/next/docs/reference/entando-cli.md b/vuepress/docs/next/docs/reference/entando-cli.md deleted file mode 100644 index 886a693043..0000000000 --- a/vuepress/docs/next/docs/reference/entando-cli.md +++ /dev/null @@ -1,400 +0,0 @@ ---- -sidebarDepth: 2 ---- -# Entando CLI - -## Overview - -The Entando Command Line Interface (CLI) provides a set of commands that accelerate common tasks such as installing a new instance of Entando, generating an Entando project via JHipster, deploying an Entando Bundle, creating an Entando Application, etc. - -## Installation - -### Prerequisites - -The basic requirements for the CLI vary depending on the category of developer tasks. The CLI is able to install secondary dependencies using the `ent check-env` command as described [here](#check-the-environment). - -| Category | Prerequisite -| :-: | :-: -|Basic Development| Git or [Git for Windows](https://gitforwindows.org) -| Install Entando in a local VM | [Multipass](https://multipass.run/#install) -| Build and publish Entando Bundles | Docker and Docker Compose -| | a Git repository for the bundle artifacts -| | a Docker Hub account (or organization) for microservice Docker images -| Deploy an Entando Bundle | a Kubernetes cluster with admin access, which can be a local cluster (created via the Entando CLI or manually) or a shared remote cluster - -::: tip - The automated option in [Getting Started](../getting-started/) will install the CLI along with an Ubuntu VM containing K3s Kubernetes and a quickstart Entando Application. -::: - -### Install the CLI -Install the current offical release of the CLI via the following command -``` bash -curl -L https://get.entando.org/cli | bash -``` - -### Check the Environment - -Use the `check-env` command to prepare your environment for development. This will verify the presence of required dependencies as well as the appropriate versions for your specific Entando instance. Certain configurations allow `check-env` to automatically install dependencies and prompt the developer for guidance or approval as needed. -``` bash -ent check-env develop -``` - -### Update the CLI -The CLI can be updated to the latest version (corresponding to the current Entando version) using - -``` sh -bash <(curl -L "https://get.entando.org/cli") --update -``` - -Run `ent check-env develop` after updating the CLI to determine if dependency versions have changed. - -Alternatively, deleting the `~/.entando` directory with `rm -rf ~/.entando` and then reinstalling the CLI, per the instructions above, will perform a clean install. This will also remove the private copies of JHipster, Entando Blueprint, etc. - - -## Available Commands -Use `ent help` to review the list of available commands - -``` -~~~~~~~~~~~~~~~~~~~ - Entando CLI -~~~~~~~~~~~~~~~~~~~ - -> Essentials: - - Activate using: ~/.entando/ent/v7.0.0/cli/v7.0.0/activate - - Deactivate using: ~/.entando/ent/v7.0.0/cli/v7.0.0/deactivate - -> Available commands: - - app => Helper for managing an Entando App - - app-info => Displays information about an Entando App - - bundler => Wrapper for the ent private installation of the Entando bundle tool - - check-env => Checks the environment for required dependencies and settings - - diag => Runs diagnostics and aggregates the related info in a .tgz file - - ecr => Helper for managing the ECR - - ent => Helper for managing the local ents - - help => Help information - - host => Helper for managing the system that hosts the quickstart VM - - jhipster => Wrapper for the ent private installation of jhipster - - kubectl => Helper for using kubectl in ent managed scenarios - - npm => Wrapper for the ent private installation of npm (mostly for internal use) - - pod => Displays information related to a set of pods - - prj => Helper for managing Entando bundle projects - - profile => Helper for managing an Entando App - - quickstart => Helper for installing Entando instances locally - - run-tests => Runs the internal tests - -> Further info about entando: - - ~/.entando/ent/v7.0.0/cli/v7.0.0/README.md - - https://www.entando.com/ - - https://developer.entando.com/ - -> ⚠ RECOMMENDED FIRST STEP ⚠ : - - Check the dependencies (ent check-env --help) -``` -Check a command's help text (`--help`) to view specific options and subcommands, e.g. `ent check-env --help`. For general configuration options related to ent itself, see `ent --help`. - -### Customize Quickstart -The `ent quickstart` command supports parameters to customize your quickstart environment. These options allow you to modify specific properties of your VM, installation versions and databases. - -For example, to reuse an existing VM: -``` sh -ent quickstart --vm-reuse=YOUR-EXISTING-VM -``` -For additional information, check the output of -``` sh -ent quickstart --help -``` - -## Common Operations -### Project Management -Procedures and commands commonly used to generate and manage Entando projects are detailed below. - -#### Project Setup -1. Create a project directory -``` sh -mkdir testProject && cd testProject -``` -2. Generate the project skeleton using the JHipster-based Entando Blueprint -``` sh -ent jhipster --blueprints entando -``` -3. Generate an entity and MFEs -``` sh -ent jhipster entity Conference -``` -4. Build the new project -``` sh -ent prj build -``` - -> Note: Using the `ent prj` wrapper avoids having to build each part of the project individually. The first run using `ent prj` can be slower due to MFE node downloads. See [the BLueprint tutorial](../../tutorials/create/ms/generate-microservices-and-micro-frontends.md) for more details. - -#### Prepare and Publish a Project Bundle -Use the publication system `pbs` to assemble your Entando project into a bundle that can be loaded into Kubernetes. This requires your GitHub credentials, an empty GitHub repository to hold your bundle artifacts, and a Docker Hub account or organization. -1. Initialize the bundle directory. This method accepts SSH and HTTPS URLs. -``` sh -ent prj pbs-init -``` -2. Publish the build artifacts to GitHub and Docker Hub -``` sh -ent prj pbs-publish -``` -3. Deploy the bundle into the Entando Component Repository -``` sh -ent prj deploy -``` -See [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-project-bundle.md) for more details. - -#### Install the Project Bundle into an Application -The CLI allows you to install a bundle without accessing the Entando App Builder. - -> Note: A bundle must be deployed before it can be installed. - -Run the following command from the project folder: -``` sh -ent prj install -``` - -If a project bundle has already been installed, use `--conflict-strategy` to adopt a strategy for existing components (CREATE, SKIP, OVERRIDE), e.g: -``` sh -ent prj install --conflict-strategy=OVERRIDE -``` -#### Run a Project Locally -1. Initialize Keycloak, which leverages Docker Compose -``` sh -ent prj ext-keycloak start -``` -2. Initialize backend microservices -``` sh -ent prj be-test-run -``` -To fetch logs from bundle plugins, use the command -``` -ent prj be-log -``` -3. Initialize one or more frontend widgets, each from its own shell -``` sh -ent prj fe-test-run -``` -Check out [Run Blueprint-generated Microservices and Micro Frontends in Dev Mode](../../tutorials/create/ms/run-local.md) for additional information. - - -#### Determine Project Identifiers -Entando uses a unique identifier for your project bundle as a way to provide additional security controls around bundle-specific resources. A unique identifier is also calculated for each microservice plugin in your project. - -Determine the project bundle ID: -```sh -ent prj get-bundle-id --auto -``` - -Determine the plugin ID of each microservice in the project: -```sh -ent prj get-plugin-id --auto --repo= -``` - -### Bundle Management -The sections below describe common bundle operations and provide the associated commands. -#### Prepare a Bundle for Publication - -Use the `ent bundler` command to prepare a bundle for publication: - -``` sh - ent bundler from-git -``` - -Alternatively, the project command `ent prj generate-cr` provides a wrapped version of `ent bundler` and prepares a bundle custom resource from a Git repository. The output of `ent prj generate-cr` is a YAML file which can be piped to `ent kubectl` for direct application to Kubernetes. - -Consult the `ent prj generate-cr` help text for command options (e.g. bundle name, description, repository). For an example of how to use `ent prj generate-cr`, refer to the [Build and Publish a Simple Bundle tutorial](../../tutorials/create/pb/publish-simple-bundle.md). -#### Extract a Bundle from an Application - -The bundler provides an interactive mode to identify the components to export from the application. Point the bundler to an existing Entando Application to extract its components (pages, content, etc.) and static assets into a custom bundle. This bundle can be used to migrate Entando components from one environment to another (e.g. Dev to QA), as a template for building a new Entando Application, or as the skeleton of an Entando solution. - -To generate the bundle folder structure for an Entando project, including a top-level descriptor file: -``` sh - ent bundler from-env -``` - -An `env.json` file to configure the application URLs and client credentials must live in the directory from which the bundler is run. - -For example: -``` json -{ - "coreBaseApi": "http://YOUR-DOMAIN-OR-IP/entando-de-app", - "componentManagerApi": "http://YOUR-DOMAIN-OR-IP/digital-exchange", - "clientId": "YOUR-CLIENT-ID", - "clientSecret": "YOUR-CLIENT-SECRET" -} -``` - -Instructions to export a bundle, including how to configure `env.json`, can be found in the [Export and Publish a Bundle tutorial](../../tutorials/create/pb/export-bundle-from-application.md). - - -#### Entando Component Repository Wrapper -Entando provides a series of `ent ecr` commands for interaction with [the Entando Component Repository](../../docs/compose/ecr-overview.md) (ECR). The following commands apply specifically and only to bundles. - - -Display the list of bundles associated with the current profile: -``` -ent ecr list -``` - -Generate a bundle and deploy it to the current profile: -``` -ent ecr deploy -``` - -The helpers `get-bundle-id` and `get-plugin-id` have been added to `ent ecr` to calculate and display unique custom resource identifiers. This provides additional security controls around bundle-specific and microservice plugin resources. - -Determine the bundle ID: -``` -ent ecr get-bundle-id YOUR-BUNDLE-REPOSITORY-URL -``` - -Determine the plugin ID: -``` -ent ecr get-plugin-id --auto YOUR-BUNDLE-REPOSITORY-URL -``` -### Profile Management -Manage and switch between different Entando configurations with `ent profile`, which uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`). - -Cloud Kubernetes tools typically create a Kubernetes context which can be linked to an Entando profile. An overview of the current connection and profile information is provided via `ent status`. - -The following commands perform common operations associated with profile management. - -#### New Profile - -Create and switch to a new profile: -``` -ent pro new [profileName] [EntandoAppName] [namespace] -``` -This sets the minimal profile data and explains next steps. - -#### Link Profile - -Link the current profile to a Kubernetes context (alias of `ent attach-kubectx`): -``` -ent pro link [contextName] -``` -This provides the instructions for ent to connect to the Kubernetes containing the Entando Application. - -#### Global Profile - -Activate the profile that ent should use across shells: -``` -ent pro use [profileName] -``` -This attempts to fully restore a profile type by considering the login and related Entando Applications. - -#### Local Profile - -Activate the profile that ent should use within the current shell: -``` -source ent pro use [profileName] -``` - -This allows ent instances in different shells to simultaneously use different Kube contexts, kubeconfigs or custom commands. The quickstart script creates a profile named "qs--{vmname}" that is associated with the Entando Application it generates. -#### Print - -Print a list of the available profiles: -``` -ent pro list -``` - -#### Delete - -Delete a profile: -``` -ent pro delete [profileName] -``` - -### Configuration Management -The output of `ent config` is a key-value archive of configurations related to the current profile. -It can serve several purposes, but a few "good to know" keys and commands are below. - -#### Commands -Print the current config archive: -``` -ent config --print -``` -Interactively edit a config archive: -``` -ent config --edit -``` -Return the value of a config key: -``` -ent config --get {key} -``` -Set the value of a config key: -``` -ent config --set {key} {value} -``` -Delete a config key: -``` -ent config --set {key} -``` -#### Keys -| Key | Definition | -|---|---| -| ENTANDO_NAMESPACE | stores the fallback namespace used by explicit or implicit runs of `ent kubectl` | -| ENTANDO_APPNAME | stores the Entando Application name related to the current profile | -| DESIGNATED_JAVA_HOME | stores the path of the Java version used internally by ent | - -## Diagnostics and Debug - -### Diagnostic Commands - -Diagnostic information can be highly useful when analyzing and troubleshooting behavior. The Getting Started guide includes steps to [automatically install](../../docs/getting-started/README.md#automatic-install) the CLI in a Multipass VM. The following commands can be run from this VM for insight into an Entando Application. - -#### Basic Information - -Display basic information about Kubernetes and Entando resources (e.g. namespace, pods, ingresses): -``` sh -ent app-info -``` - -#### Pod Logs - -Display `kubectl describe` and `kubectl logs` for each of the major Entando pods in a namespace: -``` sh -ent pod-info -``` - -#### Diagnostic Files - -List the current pods in an Entando namespace and prepare a diagnostic tar.gz: -``` sh -ent diag -``` -This outputs `kubectl describe` and `kubectl logs` for each of the fundamental Entando pods. It also exports custom resources, ingresses, deployments, "previous" pod logs, namespace events, etc. - -The directory paths of the diagnostic logs are listed, 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" -``` -### Troubleshooting -The CLI is a useful tool for debugging issues with an Entando instance. -#### Error Location -Locate error messages in the EntandoApp pods: -``` bash -ent pod grep --all "error|fail" -``` -or -``` bash -ent pod grep ".*" "error|fail" -``` -#### Extraction Error -To resolve the error "Unable to extract the application client secret": - -1. Verify that the current profile namespace and application name are correct and match the output of the following command -``` sh -ent status -``` -2. Assign the appropriate namespace and application name -``` sh -ent appname YOUR-APPNAME -ent namespace YOUR-NAMESPACE -``` - -## Reference -* Source repository: From e0ad9be1a9ce71a8d2fbf7b871c62fa9526ced95 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Tue, 19 Jul 2022 14:35:14 -0500 Subject: [PATCH 02/34] ENDOC-522 temporary --- .../docs/next/docs/getting-started/ent-api.md | 10 + .../next/docs/getting-started/ent-bundle.md | 192 ++++++++++++++++++ .../next/docs/getting-started/ent-diag.md | 62 ++++++ .../next/docs/getting-started/ent-profile.md | 92 +++++++++ .../docs/next/docs/getting-started/ent-svc.md | 3 + 5 files changed, 359 insertions(+) create mode 100644 vuepress/docs/next/docs/getting-started/ent-api.md create mode 100644 vuepress/docs/next/docs/getting-started/ent-bundle.md create mode 100644 vuepress/docs/next/docs/getting-started/ent-diag.md create mode 100644 vuepress/docs/next/docs/getting-started/ent-profile.md create mode 100644 vuepress/docs/next/docs/getting-started/ent-svc.md diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md new file mode 100644 index 0000000000..ea543552c6 --- /dev/null +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -0,0 +1,10 @@ + + +# ent API Management + + +| Command | Subcommand| Arguments| Flags | Description| +|:--|:--|:-------|:----------------------|:--| +|api|add |component_name, name|--serviceName, --serviceUrl| Add an internal API claim on the given component| +|api|add-ext|component_name, name|--serviceName, --bundle|Add an external API claim on the given component| +|api|rm|component_name, name||Removes the given API claim| \ No newline at end of file diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md new file mode 100644 index 0000000000..c4250afe0e --- /dev/null +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -0,0 +1,192 @@ +--- +sidebarDepth: 1 +--- + +# Entando Bundle CLI- Project Management +The ent bundle CLI extends the functionality and capability of Entando’s command line interface with a modular bundle management system. Starting from Entando 7.1, ent bundle orchestrates the lifecycle of a project, whether it comes with a single component or many, and packages them into convenient recognizable bundles that can be deployed on any Entando Platform. + +This document introduces the lifecyle path of a project to ... +The main steps to bring a project to a published bundle is: + +1. Initialization +2. Build +3. Run +4. Package +5. Publish +6. Generate Custom Resource + +### Bundle lifecycle +explain lifecyle briefly, +advantages: single bundle descriptor +inititialize project from hub +centralized management of APIs and services such as DB and Keycloak +instead of using git and docker repositories, it now only uses Docker + +## Bundle Commands +syntax: `ent bundle [command] [subcommand] [arguments] [flags]` +| Command | Subcommand| Arguments| Flags | Description| +|:--|:--|:-------|:----------------------|:--| +|build||component_name|--all, --all-mfe, --all-ms| Build components (mfe, ms) with a selector| +|generate-cr |||--image {image}, --digest|Generate Entando Custom Resource from a bundle project or from a Docker Repository| +|init|||--from-hub {url} |Initialize project folder structure and descriptor| +|ms|add|component_name|--stack {spring-boot l node l go} |Add ms project components +|ms | init ||| Init with scaffolding| +|ms | rm | component_name || Remove ms project component| +|mfe | add | component_name |--stack {react l angular}, --type {app-builder l widget l widget-config} | Add mfe project component| +|mfe | init ||| Init with scaffolding | +|mfe | rm | component_name || Remove mfe project component | + +## Initialization +## Build +## Package +## Publish +## Generate CR + + + +##Project Setup +1. Create a project directory +``` sh +mkdir testProject && cd testProject +``` +2. Generate the project skeleton using the JHipster-based Entando Blueprint +``` sh +ent jhipster --blueprints entando +``` +3. Generate an entity and MFEs +``` sh +ent jhipster entity Conference +``` +4. Build the new project +``` sh +ent prj build +``` + +> Note: Using the `ent prj` wrapper avoids having to build each part of the project individually. The first run using `ent prj` can be slower due to MFE node downloads. See [the BLueprint tutorial](../../tutorials/create/ms/generate-microservices-and-micro-frontends.md) for more details. + +#### Prepare and Publish a Project Bundle +Use the publication system `pbs` to assemble your Entando project into a bundle that can be loaded into Kubernetes. This requires your GitHub credentials, an empty GitHub repository to hold your bundle artifacts, and a Docker Hub account or organization. +1. Initialize the bundle directory. This method accepts SSH and HTTPS URLs. +``` sh +ent prj pbs-init +``` +2. Publish the build artifacts to GitHub and Docker Hub +``` sh +ent prj pbs-publish +``` +3. Deploy the bundle into the Entando Component Repository +``` sh +ent prj deploy +``` +See [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-project-bundle.md) for more details. + +#### Install the Project Bundle into an Application +The CLI allows you to install a bundle without accessing the Entando App Builder. + +> Note: A bundle must be deployed before it can be installed. + +Run the following command from the project folder: +``` sh +ent prj install +``` + +If a project bundle has already been installed, use `--conflict-strategy` to adopt a strategy for existing components (CREATE, SKIP, OVERRIDE), e.g: +``` sh +ent prj install --conflict-strategy=OVERRIDE +``` +#### Run a Project Locally +1. Initialize Keycloak, which leverages Docker Compose +``` sh +ent prj ext-keycloak start +``` +2. Initialize backend microservices +``` sh +ent prj be-test-run +``` +To fetch logs from bundle plugins, use the command +``` +ent prj be-log +``` +3. Initialize one or more frontend widgets, each from its own shell +``` sh +ent prj fe-test-run +``` +Check out [Run Blueprint-generated Microservices and Micro Frontends in Dev Mode](../../tutorials/create/ms/run-local.md) for additional information. + + +#### Determine Project Identifiers +Entando uses a unique identifier for your project bundle as a way to provide additional security controls around bundle-specific resources. A unique identifier is also calculated for each microservice plugin in your project. + +Determine the project bundle ID: +```sh +ent prj get-bundle-id --auto +``` + +Determine the plugin ID of each microservice in the project: +```sh +ent prj get-plugin-id --auto --repo= +``` + +### Bundle Management +The sections below describe common bundle operations and provide the associated commands. +#### Prepare a Bundle for Publication + +Use the `ent bundler` command to prepare a bundle for publication: + +``` sh + ent bundler from-git +``` + +Alternatively, the project command `ent prj generate-cr` provides a wrapped version of `ent bundler` and prepares a bundle custom resource from a Git repository. The output of `ent prj generate-cr` is a YAML file which can be piped to `ent kubectl` for direct application to Kubernetes. + +Consult the `ent prj generate-cr` help text for command options (e.g. bundle name, description, repository). For an example of how to use `ent prj generate-cr`, refer to the [Build and Publish a Simple Bundle tutorial](../../tutorials/create/pb/publish-simple-bundle.md). + +#### Extract a Bundle from an Application + +The bundler provides an interactive mode to identify the components to export from the application. Point the bundler to an existing Entando Application to extract its components (pages, content, etc.) and static assets into a custom bundle. This bundle can be used to migrate Entando components from one environment to another (e.g. Dev to QA), as a template for building a new Entando Application, or as the skeleton of an Entando solution. + +To generate the bundle folder structure for an Entando project, including a top-level descriptor file: +``` sh + ent bundler from-env +``` + +An `env.json` file to configure the application URLs and client credentials must live in the directory from which the bundler is run. + +For example: +``` json +{ + "coreBaseApi": "http://YOUR-DOMAIN-OR-IP/entando-de-app", + "componentManagerApi": "http://YOUR-DOMAIN-OR-IP/digital-exchange", + "clientId": "YOUR-CLIENT-ID", + "clientSecret": "YOUR-CLIENT-SECRET" +} +``` + +Instructions to export a bundle, including how to configure `env.json`, can be found in the [Export and Publish a Bundle tutorial](../../tutorials/create/pb/export-bundle-from-application.md). + +#### Entando Component Repository Wrapper +Entando provides a series of `ent ecr` commands for interaction with [the Entando Component Repository](../../docs/compose/ecr-overview.md) (ECR). The following commands apply specifically and only to bundles. + + +Display the list of bundles associated with the current profile: +``` +ent ecr list +``` + +Generate a bundle and deploy it to the current profile: +``` +ent ecr deploy +``` + +The helpers `get-bundle-id` and `get-plugin-id` have been added to `ent ecr` to calculate and display unique custom resource identifiers. This provides additional security controls around bundle-specific and microservice plugin resources. + +Determine the bundle ID: +``` +ent ecr get-bundle-id YOUR-BUNDLE-REPOSITORY-URL +``` + +Determine the plugin ID: +``` +ent ecr get-plugin-id --auto YOUR-BUNDLE-REPOSITORY-URL +``` + diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md new file mode 100644 index 0000000000..3bd24f9e9a --- /dev/null +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -0,0 +1,62 @@ +--- +sidebarDepth: 1 +--- + + +# Diagnostics and Debug + +### Diagnostic Commands + +Diagnostic information can be highly useful when analyzing and troubleshooting behavior. The Getting Started guide includes steps to [automatically install](../../docs/getting-started/README.md#automatic-install) the CLI in a Multipass VM. The following commands can be run from this VM for insight into an Entando Application. + +#### Basic Information + +Display basic information about Kubernetes and Entando resources (e.g. namespace, pods, ingresses): +``` sh +ent app-info +``` + +#### Pod Logs + +Display `kubectl describe` and `kubectl logs` for each of the major Entando pods in a namespace: +``` sh +ent pod-info +``` + +#### Diagnostic Files + +List the current pods in an Entando namespace and prepare a diagnostic tar.gz: +``` sh +ent diag +``` +This outputs `kubectl describe` and `kubectl logs` for each of the fundamental Entando pods. It also exports custom resources, ingresses, deployments, "previous" pod logs, namespace events, etc. + +The directory paths of the diagnostic logs are listed, 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" +``` +### Troubleshooting +The CLI is a useful tool for debugging issues with an Entando instance. +#### Error Location +Locate error messages in the EntandoApp pods: +``` bash +ent pod grep --all "error|fail" +``` +or +``` bash +ent pod grep ".*" "error|fail" +``` +#### Extraction Error +To resolve the error "Unable to extract the application client secret": + +1. Verify that the current profile namespace and application name are correct and match the output of the following command +``` sh +ent status +``` +2. Assign the appropriate namespace and application name +``` sh +ent appname YOUR-APPNAME +ent namespace YOUR-NAMESPACE +``` \ No newline at end of file diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md new file mode 100644 index 0000000000..8d22b2853c --- /dev/null +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -0,0 +1,92 @@ +--- +sidebarDepth: 1 +--- + + +# Profile Management + + +Manage and switch between different Entando configurations with `ent profile`, which uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`). + +Cloud Kubernetes tools typically create a Kubernetes context which can be linked to an Entando profile. An overview of the current connection and profile information is provided via `ent status`. + +The following commands perform common operations associated with profile management. + +## New Profile + +Create and switch to a new profile: +``` +ent pro new [profileName] [EntandoAppName] [namespace] +``` +This sets the minimal profile data and explains next steps. + +## Link Profile + +Link the current profile to a Kubernetes context (alias of `ent attach-kubectx`): +``` +ent pro link [contextName] +``` +This provides the instructions for ent to connect to the Kubernetes containing the Entando Application. + +## Global Profile + +Activate the profile that ent should use across shells: +``` +ent pro use [profileName] +``` +This attempts to fully restore a profile type by considering the login and related Entando Applications. + +## Local Profile + +Activate the profile that ent should use within the current shell: +``` +source ent pro use [profileName] +``` + +This allows ent instances in different shells to simultaneously use different Kube contexts, kubeconfigs or custom commands. The quickstart script creates a profile named "qs--{vmname}" that is associated with the Entando Application it generates. +## Print + +Print a list of the available profiles: +``` +ent pro list +``` + +## Delete + +Delete a profile: +``` +ent pro delete [profileName] +``` + +### Configuration Management +The output of `ent config` is a key-value archive of configurations related to the current profile. +It can serve several purposes, but a few "good to know" keys and commands are below. + +#### Commands +Print the current config archive: +``` +ent config --print +``` +Interactively edit a config archive: +``` +ent config --edit +``` +Return the value of a config key: +``` +ent config --get {key} +``` +Set the value of a config key: +``` +ent config --set {key} {value} +``` +Delete a config key: +``` +ent config --set {key} +``` +#### Keys +| Key | Definition | +|---|---| +| ENTANDO_NAMESPACE | stores the fallback namespace used by explicit or implicit runs of `ent kubectl` | +| ENTANDO_APPNAME | stores the Entando Application name related to the current profile | +| DESIGNATED_JAVA_HOME | stores the path of the Java version used internally by ent | + diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md new file mode 100644 index 0000000000..b497c4f967 --- /dev/null +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -0,0 +1,3 @@ +--- +sidebarDepth: 1 +--- From 1537907f89fa852d0a4f8662312c0d62a783924c Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Tue, 19 Jul 2022 15:04:12 -0500 Subject: [PATCH 03/34] ENDOC-522 corrections --- vuepress/docs/.vuepress/next.js | 4 - .../docs/next/docs/getting-started/README.md | 4 +- .../docs/next/docs/getting-started/ent-api.md | 6 - .../next/docs/getting-started/ent-bundle.md | 189 ------------------ .../next/docs/getting-started/ent-diag.md | 58 ------ .../next/docs/getting-started/ent-profile.md | 89 --------- vuepress/docs/next/tutorials/README.md | 2 +- .../docs/next/tutorials/create/mfe/react.md | 2 +- ...erate-microservices-and-micro-frontends.md | 2 +- .../pb/export-bundle-from-application.md | 2 +- .../create/pb/github-actions-workflow.md | 2 +- .../create/pb/publish-project-bundle.md | 2 +- .../create/pb/publish-simple-bundle.md | 2 +- .../tutorials/devops/plugin-configuration.md | 2 +- .../next/tutorials/solution/entando-hub.md | 2 +- 15 files changed, 11 insertions(+), 357 deletions(-) diff --git a/vuepress/docs/.vuepress/next.js b/vuepress/docs/.vuepress/next.js index eb50c60754..6198e4f423 100644 --- a/vuepress/docs/.vuepress/next.js +++ b/vuepress/docs/.vuepress/next.js @@ -156,10 +156,6 @@ module.exports = { { title: 'Reference', children: [ - { - title: 'Entando CLI', - path: path + 'reference/entando-cli.md' - }, { title: 'Deployment Structure', path: path + 'reference/deployment-structure.md' diff --git a/vuepress/docs/next/docs/getting-started/README.md b/vuepress/docs/next/docs/getting-started/README.md index 988472b278..5546bcbb6f 100644 --- a/vuepress/docs/next/docs/getting-started/README.md +++ b/vuepress/docs/next/docs/getting-started/README.md @@ -21,7 +21,7 @@ The following steps launch an Ubuntu VM via Multipass, install Kubernetes, then 1. Install [Multipass](https://multipass.run/#install) -2. Install Entando into Kubernetes on Ubuntu using the [Entando CLI](../reference/entando-cli.md) +2. Install Entando into Kubernetes on Ubuntu using the [Entando CLI](entando-cli.md) ```sh curl -sfL https://get.entando.org | bash @@ -134,7 +134,7 @@ sudo kubectl get pods -A You now have a local instance of Kubernetes up and running. ::: -Now that Kubernetes is running, you can use kubectl to send commands directly to K3s from the host machine, rather than from within the VM. To set this up with the [ent CLI](../reference/entando-cli.md), run `ent attach-vm quickstart` and then use `ent kubectl` for any calls to K8s. Alternatively, see the K3s documentation to [access your cluster with kubectl](https://rancher.com/docs/k3s/latest/en/cluster-access/). +Now that Kubernetes is running, you can use kubectl to send commands directly to K3s from the host machine, rather than from within the VM. To set this up with the [ent CLI](entando-cli.md), run `ent attach-vm quickstart` and then use `ent kubectl` for any calls to K8s. Alternatively, see the K3s documentation to [access your cluster with kubectl](https://rancher.com/docs/k3s/latest/en/cluster-access/). ### Prepare Kubernetes diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md index ea543552c6..fd40910d9e 100644 --- a/vuepress/docs/next/docs/getting-started/ent-api.md +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -1,10 +1,4 @@ -# ent API Management -| Command | Subcommand| Arguments| Flags | Description| -|:--|:--|:-------|:----------------------|:--| -|api|add |component_name, name|--serviceName, --serviceUrl| Add an internal API claim on the given component| -|api|add-ext|component_name, name|--serviceName, --bundle|Add an external API claim on the given component| -|api|rm|component_name, name||Removes the given API claim| \ No newline at end of file diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index c4250afe0e..b497c4f967 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -1,192 +1,3 @@ --- sidebarDepth: 1 --- - -# Entando Bundle CLI- Project Management -The ent bundle CLI extends the functionality and capability of Entando’s command line interface with a modular bundle management system. Starting from Entando 7.1, ent bundle orchestrates the lifecycle of a project, whether it comes with a single component or many, and packages them into convenient recognizable bundles that can be deployed on any Entando Platform. - -This document introduces the lifecyle path of a project to ... -The main steps to bring a project to a published bundle is: - -1. Initialization -2. Build -3. Run -4. Package -5. Publish -6. Generate Custom Resource - -### Bundle lifecycle -explain lifecyle briefly, -advantages: single bundle descriptor -inititialize project from hub -centralized management of APIs and services such as DB and Keycloak -instead of using git and docker repositories, it now only uses Docker - -## Bundle Commands -syntax: `ent bundle [command] [subcommand] [arguments] [flags]` -| Command | Subcommand| Arguments| Flags | Description| -|:--|:--|:-------|:----------------------|:--| -|build||component_name|--all, --all-mfe, --all-ms| Build components (mfe, ms) with a selector| -|generate-cr |||--image {image}, --digest|Generate Entando Custom Resource from a bundle project or from a Docker Repository| -|init|||--from-hub {url} |Initialize project folder structure and descriptor| -|ms|add|component_name|--stack {spring-boot l node l go} |Add ms project components -|ms | init ||| Init with scaffolding| -|ms | rm | component_name || Remove ms project component| -|mfe | add | component_name |--stack {react l angular}, --type {app-builder l widget l widget-config} | Add mfe project component| -|mfe | init ||| Init with scaffolding | -|mfe | rm | component_name || Remove mfe project component | - -## Initialization -## Build -## Package -## Publish -## Generate CR - - - -##Project Setup -1. Create a project directory -``` sh -mkdir testProject && cd testProject -``` -2. Generate the project skeleton using the JHipster-based Entando Blueprint -``` sh -ent jhipster --blueprints entando -``` -3. Generate an entity and MFEs -``` sh -ent jhipster entity Conference -``` -4. Build the new project -``` sh -ent prj build -``` - -> Note: Using the `ent prj` wrapper avoids having to build each part of the project individually. The first run using `ent prj` can be slower due to MFE node downloads. See [the BLueprint tutorial](../../tutorials/create/ms/generate-microservices-and-micro-frontends.md) for more details. - -#### Prepare and Publish a Project Bundle -Use the publication system `pbs` to assemble your Entando project into a bundle that can be loaded into Kubernetes. This requires your GitHub credentials, an empty GitHub repository to hold your bundle artifacts, and a Docker Hub account or organization. -1. Initialize the bundle directory. This method accepts SSH and HTTPS URLs. -``` sh -ent prj pbs-init -``` -2. Publish the build artifacts to GitHub and Docker Hub -``` sh -ent prj pbs-publish -``` -3. Deploy the bundle into the Entando Component Repository -``` sh -ent prj deploy -``` -See [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-project-bundle.md) for more details. - -#### Install the Project Bundle into an Application -The CLI allows you to install a bundle without accessing the Entando App Builder. - -> Note: A bundle must be deployed before it can be installed. - -Run the following command from the project folder: -``` sh -ent prj install -``` - -If a project bundle has already been installed, use `--conflict-strategy` to adopt a strategy for existing components (CREATE, SKIP, OVERRIDE), e.g: -``` sh -ent prj install --conflict-strategy=OVERRIDE -``` -#### Run a Project Locally -1. Initialize Keycloak, which leverages Docker Compose -``` sh -ent prj ext-keycloak start -``` -2. Initialize backend microservices -``` sh -ent prj be-test-run -``` -To fetch logs from bundle plugins, use the command -``` -ent prj be-log -``` -3. Initialize one or more frontend widgets, each from its own shell -``` sh -ent prj fe-test-run -``` -Check out [Run Blueprint-generated Microservices and Micro Frontends in Dev Mode](../../tutorials/create/ms/run-local.md) for additional information. - - -#### Determine Project Identifiers -Entando uses a unique identifier for your project bundle as a way to provide additional security controls around bundle-specific resources. A unique identifier is also calculated for each microservice plugin in your project. - -Determine the project bundle ID: -```sh -ent prj get-bundle-id --auto -``` - -Determine the plugin ID of each microservice in the project: -```sh -ent prj get-plugin-id --auto --repo= -``` - -### Bundle Management -The sections below describe common bundle operations and provide the associated commands. -#### Prepare a Bundle for Publication - -Use the `ent bundler` command to prepare a bundle for publication: - -``` sh - ent bundler from-git -``` - -Alternatively, the project command `ent prj generate-cr` provides a wrapped version of `ent bundler` and prepares a bundle custom resource from a Git repository. The output of `ent prj generate-cr` is a YAML file which can be piped to `ent kubectl` for direct application to Kubernetes. - -Consult the `ent prj generate-cr` help text for command options (e.g. bundle name, description, repository). For an example of how to use `ent prj generate-cr`, refer to the [Build and Publish a Simple Bundle tutorial](../../tutorials/create/pb/publish-simple-bundle.md). - -#### Extract a Bundle from an Application - -The bundler provides an interactive mode to identify the components to export from the application. Point the bundler to an existing Entando Application to extract its components (pages, content, etc.) and static assets into a custom bundle. This bundle can be used to migrate Entando components from one environment to another (e.g. Dev to QA), as a template for building a new Entando Application, or as the skeleton of an Entando solution. - -To generate the bundle folder structure for an Entando project, including a top-level descriptor file: -``` sh - ent bundler from-env -``` - -An `env.json` file to configure the application URLs and client credentials must live in the directory from which the bundler is run. - -For example: -``` json -{ - "coreBaseApi": "http://YOUR-DOMAIN-OR-IP/entando-de-app", - "componentManagerApi": "http://YOUR-DOMAIN-OR-IP/digital-exchange", - "clientId": "YOUR-CLIENT-ID", - "clientSecret": "YOUR-CLIENT-SECRET" -} -``` - -Instructions to export a bundle, including how to configure `env.json`, can be found in the [Export and Publish a Bundle tutorial](../../tutorials/create/pb/export-bundle-from-application.md). - -#### Entando Component Repository Wrapper -Entando provides a series of `ent ecr` commands for interaction with [the Entando Component Repository](../../docs/compose/ecr-overview.md) (ECR). The following commands apply specifically and only to bundles. - - -Display the list of bundles associated with the current profile: -``` -ent ecr list -``` - -Generate a bundle and deploy it to the current profile: -``` -ent ecr deploy -``` - -The helpers `get-bundle-id` and `get-plugin-id` have been added to `ent ecr` to calculate and display unique custom resource identifiers. This provides additional security controls around bundle-specific and microservice plugin resources. - -Determine the bundle ID: -``` -ent ecr get-bundle-id YOUR-BUNDLE-REPOSITORY-URL -``` - -Determine the plugin ID: -``` -ent ecr get-plugin-id --auto YOUR-BUNDLE-REPOSITORY-URL -``` - diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md index 3bd24f9e9a..52d668bdd0 100644 --- a/vuepress/docs/next/docs/getting-started/ent-diag.md +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -2,61 +2,3 @@ sidebarDepth: 1 --- - -# Diagnostics and Debug - -### Diagnostic Commands - -Diagnostic information can be highly useful when analyzing and troubleshooting behavior. The Getting Started guide includes steps to [automatically install](../../docs/getting-started/README.md#automatic-install) the CLI in a Multipass VM. The following commands can be run from this VM for insight into an Entando Application. - -#### Basic Information - -Display basic information about Kubernetes and Entando resources (e.g. namespace, pods, ingresses): -``` sh -ent app-info -``` - -#### Pod Logs - -Display `kubectl describe` and `kubectl logs` for each of the major Entando pods in a namespace: -``` sh -ent pod-info -``` - -#### Diagnostic Files - -List the current pods in an Entando namespace and prepare a diagnostic tar.gz: -``` sh -ent diag -``` -This outputs `kubectl describe` and `kubectl logs` for each of the fundamental Entando pods. It also exports custom resources, ingresses, deployments, "previous" pod logs, namespace events, etc. - -The directory paths of the diagnostic logs are listed, 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" -``` -### Troubleshooting -The CLI is a useful tool for debugging issues with an Entando instance. -#### Error Location -Locate error messages in the EntandoApp pods: -``` bash -ent pod grep --all "error|fail" -``` -or -``` bash -ent pod grep ".*" "error|fail" -``` -#### Extraction Error -To resolve the error "Unable to extract the application client secret": - -1. Verify that the current profile namespace and application name are correct and match the output of the following command -``` sh -ent status -``` -2. Assign the appropriate namespace and application name -``` sh -ent appname YOUR-APPNAME -ent namespace YOUR-NAMESPACE -``` \ No newline at end of file diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md index 8d22b2853c..b497c4f967 100644 --- a/vuepress/docs/next/docs/getting-started/ent-profile.md +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -1,92 +1,3 @@ --- sidebarDepth: 1 --- - - -# Profile Management - - -Manage and switch between different Entando configurations with `ent profile`, which uses Kubernetes contexts, kubeconfig files, and/or custom commands (refer to `ent profile first-use-readme`). - -Cloud Kubernetes tools typically create a Kubernetes context which can be linked to an Entando profile. An overview of the current connection and profile information is provided via `ent status`. - -The following commands perform common operations associated with profile management. - -## New Profile - -Create and switch to a new profile: -``` -ent pro new [profileName] [EntandoAppName] [namespace] -``` -This sets the minimal profile data and explains next steps. - -## Link Profile - -Link the current profile to a Kubernetes context (alias of `ent attach-kubectx`): -``` -ent pro link [contextName] -``` -This provides the instructions for ent to connect to the Kubernetes containing the Entando Application. - -## Global Profile - -Activate the profile that ent should use across shells: -``` -ent pro use [profileName] -``` -This attempts to fully restore a profile type by considering the login and related Entando Applications. - -## Local Profile - -Activate the profile that ent should use within the current shell: -``` -source ent pro use [profileName] -``` - -This allows ent instances in different shells to simultaneously use different Kube contexts, kubeconfigs or custom commands. The quickstart script creates a profile named "qs--{vmname}" that is associated with the Entando Application it generates. -## Print - -Print a list of the available profiles: -``` -ent pro list -``` - -## Delete - -Delete a profile: -``` -ent pro delete [profileName] -``` - -### Configuration Management -The output of `ent config` is a key-value archive of configurations related to the current profile. -It can serve several purposes, but a few "good to know" keys and commands are below. - -#### Commands -Print the current config archive: -``` -ent config --print -``` -Interactively edit a config archive: -``` -ent config --edit -``` -Return the value of a config key: -``` -ent config --get {key} -``` -Set the value of a config key: -``` -ent config --set {key} {value} -``` -Delete a config key: -``` -ent config --set {key} -``` -#### Keys -| Key | Definition | -|---|---| -| ENTANDO_NAMESPACE | stores the fallback namespace used by explicit or implicit runs of `ent kubectl` | -| ENTANDO_APPNAME | stores the Entando Application name related to the current profile | -| DESIGNATED_JAVA_HOME | stores the path of the Java version used internally by ent | - diff --git a/vuepress/docs/next/tutorials/README.md b/vuepress/docs/next/tutorials/README.md index f3ea88765c..4627625c5b 100644 --- a/vuepress/docs/next/tutorials/README.md +++ b/vuepress/docs/next/tutorials/README.md @@ -52,5 +52,5 @@ table th:nth-of-type(3) { | [Set Up Entando on Azure Kubernetes Service (AKS)](./getting-started/azure-install.md) |[Connect Your Entando Application to an External Database](./devops/external-db.md) | [Manage NGINX](./devops/manage-nginx.md) | [Set Up Entando on Google Kubernetes Engine (GKE)](./getting-started/gke-install.md) | [Install the Standard Demo Application](./solution/install-standard-demo.md)| [Setup Plugin Profiles](./devops/plugin-configuration.md) | [Set Up Entando on Red Hat OpenShift](./getting-started/openshift-install.md) | [Configure the Entando Operator](./devops/entando-operator.md) | -| [Entando CLI Reference](../docs/reference/entando-cli.md) | | +| [Entando CLI Reference](../docs/getting-started/entando-cli.md) | | diff --git a/vuepress/docs/next/tutorials/create/mfe/react.md b/vuepress/docs/next/tutorials/create/mfe/react.md index b9537d67cb..a47c39d4fc 100644 --- a/vuepress/docs/next/tutorials/create/mfe/react.md +++ b/vuepress/docs/next/tutorials/create/mfe/react.md @@ -6,7 +6,7 @@ sidebarDepth: 2 ## Prerequisites - [A working instance of Entando](../../../docs/getting-started/) -- Use the [Entando CLI](../../../docs/reference/entando-cli.md) to verify all dependencies are installed: +- Use the [Entando CLI](../../../docs/getting-started/entando-cli.md) to verify all dependencies are installed: ``` ent check-env develop ``` diff --git a/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md b/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md index 5d8cdf9ac6..532ade2005 100644 --- a/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md +++ b/vuepress/docs/next/tutorials/create/ms/generate-microservices-and-micro-frontends.md @@ -19,7 +19,7 @@ The general flow of component generation is: 5. Install your Entando Bundle into your Entando Application(s) ## Prerequisites -Use the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment) to verify environmental dependencies (e.g. Java, npm, git, JHipster, Entando Blueprint). +Use the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment) to verify environmental dependencies (e.g. Java, npm, git, JHipster, Entando Blueprint). ``` sh ent check-env develop ``` 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 ae71c13de6..12ff81d60f 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 @@ -13,7 +13,7 @@ Use the bundler command to export a bundle of components from an existing Entand This command generates the same bundle directory structure as an Entando project, including a bundle descriptor file. ### Prerequisites -* Use the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment) to verify prerequisites (e.g. git, entando-bundler): +* 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 ``` diff --git a/vuepress/docs/next/tutorials/create/pb/github-actions-workflow.md b/vuepress/docs/next/tutorials/create/pb/github-actions-workflow.md index 79d19e7ad5..1a87e47031 100644 --- a/vuepress/docs/next/tutorials/create/pb/github-actions-workflow.md +++ b/vuepress/docs/next/tutorials/create/pb/github-actions-workflow.md @@ -10,7 +10,7 @@ This tutorial shows how to use the JHipster `ci-cd` sub-generator to quickly cre ## Prerequisites * An existing project with a GitHub repository. See the [Entando Component Generator](../ms/generate-microservices-and-micro-frontends.md) to create a new one. * [GitHub Actions](https://github.com/features/actions). These are enabled by default without additional configuration. Please note public repositories currently qualify for unlimited usage but private repositories can encounter usage restrictions. -* Use the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment) to verify you have the command line prerequisites in place for this tutorial (e.g. npm, git, JHipster). +* Use the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment) to verify you have the command line prerequisites in place for this tutorial (e.g. npm, git, JHipster). ## Create a Backend Workflow diff --git a/vuepress/docs/next/tutorials/create/pb/publish-project-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-project-bundle.md index d809426c91..a6fc4c9d91 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-project-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-project-bundle.md @@ -8,7 +8,7 @@ This tutorial demonstrates how to deploy an existing Entando project directory i The Entando CLI (ent) automates many of the tasks involved in deploying an Entando Bundle, but you can also choose to perform these tasks manually. ## Prerequisites -* Use the [Entando CLI](../../../docs/reference/entando-cli.md#check-the-environment) to verify you have the prerequisites in place (e.g. Java, npm, git) +* Use the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment) to verify you have the prerequisites in place (e.g. Java, npm, git) ``` sh ent check-env develop ``` diff --git a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md index 475472a18b..6599287df4 100644 --- a/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md +++ b/vuepress/docs/next/tutorials/create/pb/publish-simple-bundle.md @@ -7,7 +7,7 @@ sidebarDepth: 2 In this tutorial, you will learn how to create a simple Entando Bundle and deploy it into the [Entando Component Repository](../../../docs/getting-started/concepts-overview.md#entando-component-repository) (ECR). 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-the-environment) to verify all dependencies are installed (e.g. Java, npm, Git). +* Use the [Entando CLI](../../../docs/getting-started/entando-cli.md#check-the-environment) to verify all dependencies are installed (e.g. Java, npm, Git). ``` sh ent check-env develop ``` diff --git a/vuepress/docs/next/tutorials/devops/plugin-configuration.md b/vuepress/docs/next/tutorials/devops/plugin-configuration.md index 488915bef3..d38f8a5886 100644 --- a/vuepress/docs/next/tutorials/devops/plugin-configuration.md +++ b/vuepress/docs/next/tutorials/devops/plugin-configuration.md @@ -31,7 +31,7 @@ resources.limits.memory: integer, mebibytes A profile is a set of configurations encoded as YAML but embedded in the `OperatorConfigMap` as a string, since ConfigMaps cannot be multilevel. The examples below use `YOUR-PLUGIN-ID` and `YOUR-PROFILE-NAME` as placeholders for your names. Also note `|-` in the sample codes to specify each new line is read as such. ### Retrieve the Plugin ID -You will need to [retrieve the Plugin ID](../../docs/reference/entando-cli.md) which is calculated during installation and written to the EntandoPlugin Custom Resource as part of the deployment of the plugin microservice. Use the following command from the project directory +You will need to [retrieve the Plugin ID](../../docs/getting-started/entando-cli.md) which is calculated during installation and written to the EntandoPlugin Custom Resource as part of the deployment of the plugin microservice. Use the following command from the project directory ```sh ent prj get-plugin-id --auto ``` diff --git a/vuepress/docs/next/tutorials/solution/entando-hub.md b/vuepress/docs/next/tutorials/solution/entando-hub.md index d3523d34a6..c267110977 100644 --- a/vuepress/docs/next/tutorials/solution/entando-hub.md +++ b/vuepress/docs/next/tutorials/solution/entando-hub.md @@ -27,7 +27,7 @@ The Hub is installed using the Entando Component Repository (ECR) and two Entand ### Prerequisites - An Entando Application on any Kubernetes provider. Follow the [tutorials](../#operations) appropriate to your environment to install the Entando platform. -- The [ent command line tool](../../docs/reference/entando-cli.md#overview), installed and connected to your Kubernetes instance. +- The [ent command line tool](../../docs/getting-started/entando-cli.md), installed and connected to your Kubernetes instance. ### Automatically Access the Hub from the App Builder 1. Login to your App Builder From 7f9eb09b83cc7aaeda5cb2ed54491cc037fe2a64 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Wed, 20 Jul 2022 15:27:27 -0700 Subject: [PATCH 04/34] ent-profile-edits --- .../next/docs/getting-started/ent-profile.md | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md index b497c4f967..6d07c19721 100644 --- a/vuepress/docs/next/docs/getting-started/ent-profile.md +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -1,3 +1,92 @@ --- sidebarDepth: 1 --- + + +# Profile Management + +The [Entando CLI](entando-cli.md) can define a collection of configuration variables to full describe an Entando instance. One or more profiles can be created to store configuration settings for the instance. The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional details. A profile with this information is automatically generated for a quickstart application. + +At minimum, a configuration must consist of the key-value pairs specifying the application name and namespace. To run the application, the Kubernetes connection must also be provided. Cloud Kubernetes tools typically create a Kube context, which can be linked to an Entando profile. An overview of the current connection and profile information is provided via `ent status`. + +The following commands perform common operations associated with profile management. + +## New Profile + +Create and switch to a new profile: +``` +ent pro new [profileName] [EntandoAppName] [namespace] +``` +This sets the minimal profile data and outputs next steps. + +## Link Profile + +Link the current profile to a Kubernetes context (alias of `ent attach-kubectx`): +``` +ent pro link [contextName] +``` +This provides ent with instructions to connect to the Kubernetes containing the Entando Application. + +## Global Profile + +Activate the profile that ent should use across shells: +``` +ent pro use [profileName] +``` +This attempts to fully restore a profile by informing the login and related Entando applications. + +## Local Profile + +Activate the profile that ent should use within the current shell: +``` +source ent pro use [profileName] +``` + +This allows ent instances in different shells to simultaneously use different Kube contexts, kubeconfigs or custom commands. The quickstart script creates a profile named "qs--{vmname}" that is associated with the Entando Application it generates. +## Print + +Print a list of the available profiles: +``` +ent pro list +``` + +## Delete + +Delete a profile: +``` +ent pro delete [profileName] +``` + +### Configuration Management +The output of `ent config` is a key-value archive of configuration settings related to the current profile. +It can serve several purposes, but a few useful commands and keys are listed below. + +#### Commands +Print the current config archive: +``` +ent config --print +``` +Interactively edit a config archive: +``` +ent config --edit +``` +Return the value of a config key: +``` +ent config --get {key} +``` +Set the value of a config key: +``` +ent config --set {key} {value} +``` +Delete a config key: +``` +ent config --set {key} +``` +#### Keys +| Key | Definition | +|---|---| +| ENTANDO_NAMESPACE | stores the fallback namespace used by explicit or implicit runs of `ent kubectl` | +| ENTANDO_APPNAME | stores the Entando Application name related to the current profile | +| DESIGNATED_JAVA_HOME | stores the path of the Java version used internally by ent | + + From 4c43781bb9fb68fff229bacbae2c48a31ae5a6e6 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Thu, 21 Jul 2022 11:36:25 -0700 Subject: [PATCH 05/34] ENDOC-522 ent profile --- vuepress/docs/next/docs/getting-started/ent-profile.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md index 6d07c19721..3464fb5575 100644 --- a/vuepress/docs/next/docs/getting-started/ent-profile.md +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -5,7 +5,7 @@ sidebarDepth: 1 # Profile Management -The [Entando CLI](entando-cli.md) can define a collection of configuration variables to full describe an Entando instance. One or more profiles can be created to store configuration settings for the instance. The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional details. A profile with this information is automatically generated for a quickstart application. +The [Entando CLI](entando-cli.md) can define a collection of configuration variables to fully describe an Entando instance. One or more profiles can be created to store configuration settings for a particular instance. The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional details. A profile with this information is automatically generated for a quickstart application. At minimum, a configuration must consist of the key-value pairs specifying the application name and namespace. To run the application, the Kubernetes connection must also be provided. Cloud Kubernetes tools typically create a Kube context, which can be linked to an Entando profile. An overview of the current connection and profile information is provided via `ent status`. @@ -33,7 +33,7 @@ Activate the profile that ent should use across shells: ``` ent pro use [profileName] ``` -This attempts to fully restore a profile by informing the login and related Entando applications. +This initializes the profile ent should use by default. ## Local Profile From 86b503ad1931dab92e8ee20cb8dd6a5a29ce31ed Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Fri, 22 Jul 2022 15:25:40 -0500 Subject: [PATCH 06/34] ENDOC-522 cli main update --- .../next/docs/getting-started/entando-cli.md | 47 +++++-------------- 1 file changed, 12 insertions(+), 35 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/entando-cli.md b/vuepress/docs/next/docs/getting-started/entando-cli.md index 63a6274681..4ff4e9afd0 100644 --- a/vuepress/docs/next/docs/getting-started/entando-cli.md +++ b/vuepress/docs/next/docs/getting-started/entando-cli.md @@ -4,7 +4,7 @@ sidebarDepth: 1 # Entando CLI -The Entando Command Line Interface (CLI) tool--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 overview covers the basic install, set-up, and command list for the ent tool. +The Entando Command Line Interface (CLI), **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 overview, and a few operations to start using the ent tool. For specific topics, follow these links: 1. [ent bundle: Project Management](ent-bundle.md) @@ -26,8 +26,7 @@ The basic requirements for the CLI vary depending on the type of developer tasks | Deploy an Entando Bundle | a Kubernetes cluster with admin access or a shared remote cluster >TIP ->The automatic option in [Getting Started](../getting-started/) will install the CLI along with an Ubuntu VM containing K3s Kubernetes and a quickstart Entando Application. - +>The automatic option in [Getting Started](../getting-started/) will install the CLI along with a quickstart Entando Application. ## Install the CLI Install the current offical release of the CLI with the following command: @@ -37,7 +36,7 @@ curl -L https://get.entando.org/cli | bash ## Commands Overview Use `ent help` to review the list of available commands. - +Use `ent COMMAND --help` to see the details for each command. ``` ~~~~~~~~~~~~~~~~~~~ Entando CLI @@ -75,6 +74,7 @@ ent [command] [subcommand] [name] [flags] > ⚠ RECOMMENDED FIRST STEP ⚠ : - Check the dependencies (ent check-env --help) ``` +** New for version 7.1 ** ``` ~~~~~~~~~~~~~~~~~~~ ent bundle CLI @@ -103,51 +103,28 @@ COMMANDS run Run bundle components ``` - - ### Check the Environment -Use the `check-env` command to prepare your environment for development. This will verify the presence of required dependencies as well as the appropriate versions for your specific Entando instance. Typically, it will automatically install dependencies and prompt the developer for guidance or approval as needed. -``` bash +The `check-env` command verifies the presence of required dependencies and the appropriate versions for your Entando instance, automatically installing dependencies with developer guidance. +``` ent check-env develop ``` ->Check a command's help text (`--help`) to view specific options and subcommands, e.g. `ent check-env --help`. ### Update the CLI -To update ent to the latest version: +To update ent to the latest version. Run `ent check-env develop` after all updates to check dependecies. ``` sh bash <(curl -L "https://get.entando.org/cli") --update ``` - -Run `ent check-env develop` after updating to determine if dependency versions have changed. - -Alternatively, deleting the `~/.entando` directory with `rm -rf ~/.entando` and then reinstalling the CLI, per the instructions above, will perform a clean install. This will also remove the private copies of JHipster, Entando Blueprint, etc. +>Alternatively, to perform a clean install, delete the `~/.entando` directory with `rm -rf ~/.entando`. Then reinstall the CLI with the instructions above. This will also remove the private copies of JHipster, Entando Blueprint, etc. ### Customize Quickstart The `ent quickstart` command supports parameters to customize your quickstart environment. These options allow you to modify specific properties of your VM, installation versions and databases. -For example, to reuse an existing VM: -``` sh -ent quickstart --vm-reuse=YOUR-EXISTING-VM -``` -For additional information, check the output of -``` sh -ent quickstart --help -``` - +|Operation |Syntax|Description| +|:--|:--|:--| +|ent quickstart| ent quickstart --vm-reuse=YOUR-EXISTING-VM| Reuse an existing VM +||ent quickstart --release="v7.2.0" | Use a specific release version for the install ### Reference From 7da80e207874a022f40824937d7b1fca6d14acaf Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Sat, 23 Jul 2022 12:33:50 -0700 Subject: [PATCH 07/34] ENDOC-522 reformat ent profile page --- .../next/docs/getting-started/ent-profile.md | 137 +++++++----------- 1 file changed, 52 insertions(+), 85 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md index 3464fb5575..75b77c2664 100644 --- a/vuepress/docs/next/docs/getting-started/ent-profile.md +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -3,90 +3,57 @@ sidebarDepth: 1 --- -# Profile Management - -The [Entando CLI](entando-cli.md) can define a collection of configuration variables to fully describe an Entando instance. One or more profiles can be created to store configuration settings for a particular instance. The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional details. A profile with this information is automatically generated for a quickstart application. - -At minimum, a configuration must consist of the key-value pairs specifying the application name and namespace. To run the application, the Kubernetes connection must also be provided. Cloud Kubernetes tools typically create a Kube context, which can be linked to an Entando profile. An overview of the current connection and profile information is provided via `ent status`. - -The following commands perform common operations associated with profile management. - -## New Profile - -Create and switch to a new profile: -``` -ent pro new [profileName] [EntandoAppName] [namespace] -``` -This sets the minimal profile data and outputs next steps. - -## Link Profile - -Link the current profile to a Kubernetes context (alias of `ent attach-kubectx`): -``` -ent pro link [contextName] -``` -This provides ent with instructions to connect to the Kubernetes containing the Entando Application. - -## Global Profile - -Activate the profile that ent should use across shells: -``` -ent pro use [profileName] -``` -This initializes the profile ent should use by default. - -## Local Profile - -Activate the profile that ent should use within the current shell: -``` -source ent pro use [profileName] -``` - -This allows ent instances in different shells to simultaneously use different Kube contexts, kubeconfigs or custom commands. The quickstart script creates a profile named "qs--{vmname}" that is associated with the Entando Application it generates. -## Print - -Print a list of the available profiles: -``` -ent pro list -``` - -## Delete - -Delete a profile: -``` -ent pro delete [profileName] -``` - -### Configuration Management -The output of `ent config` is a key-value archive of configuration settings related to the current profile. -It can serve several purposes, but a few useful commands and keys are listed below. - -#### Commands -Print the current config archive: -``` -ent config --print -``` -Interactively edit a config archive: -``` -ent config --edit -``` -Return the value of a config key: -``` -ent config --get {key} -``` -Set the value of a config key: -``` -ent config --set {key} {value} -``` -Delete a config key: -``` -ent config --set {key} -``` -#### Keys -| Key | Definition | -|---|---| -| ENTANDO_NAMESPACE | stores the fallback namespace used by explicit or implicit runs of `ent kubectl` | -| ENTANDO_APPNAME | stores the Entando Application name related to the current profile | -| DESIGNATED_JAVA_HOME | stores the path of the Java version used internally by ent | +# Overview + +The [Entando CLI](entando-cli.md) can define a collection of configuration variables to fully describe an Entando instance. One or more profiles can be created to store configuration settings for a particular instance. A profile with this information is automatically generated for a quickstart application. + +At minimum, a profile configuration must consist of the key-value pairs specifying the application name and namespace. To run the application, the Kubernetes connection must also be provided. Cloud Kubernetes tools typically create a Kube context, which can be linked to an Entando profile. + +## Profile Management + +Common operations associated with profile management are detailed below. + +The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional information. + +| Command | Definition +| :- | :- +| `ent status` | Returns current connection and profile information +| `ent pro new [profileName] [EntandoAppName] [namespace]` | Create and switch to a new profile +| `ent pro link [contextName]` | Link the current profile to a Kubernetes context +| `ent pro use [profileName]` | Activate the default profile +| `source ent pro use [profileName]` | Activate the current profile +| `ent pro list` | Print a list of the available profiles +| `ent pro delete [profileName]` | Delete a profile + +**Command details:** +- `ent pro new`: Sets the minimal profile data and outputs next steps. + +- `ent pro link`: Provides ent with instructions to connect to the Kubernetes containing the Entando Application. Alias of `ent attach-kubectx`. + +- `ent pro use`: Initializes the global profile ent should use across shells. + +- `source ent pro use`: Initializes the local profile ent should use within the current shell. Allows ent instances in different shells to simultaneously use different Kube contexts, kubeconfigs or custom commands. The quickstart script creates a profile named "qs--{vmname}" that is associated with the Entando Application it generates. + +## Configuration Management + +The output of `ent config` is a key-value archive of configuration settings related to the current profile. The following commands and keys especially notable. + +### Commands + +| Command | Definition +| :- | :- +| `ent config --print` | Print the current config archive +| `ent config --edit` | Interactively edit a config archive +| `ent config --get {key}` | Return the value of a config key +| `ent config --set {key} {value}` | Set the value of a config key +| `ent config --set {key}` | Delete a config key + +### Keys + +| Key | Definition +|---|--- +| ENTANDO_NAMESPACE | Stores the fallback namespace used by explicit or implicit runs of `ent kubectl` +| ENTANDO_APPNAME | Stores the Entando Application name related to the current profile +| DESIGNATED_JAVA_HOME | Stores the path of the Java version used internally by ent From 34faf450a8ad9732ef05e4b42f503910639c88b6 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Mon, 25 Jul 2022 09:54:05 -0700 Subject: [PATCH 08/34] ENDOC-522 ent profile fix --- vuepress/docs/next/docs/getting-started/ent-profile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md index 75b77c2664..9ebb49fe8a 100644 --- a/vuepress/docs/next/docs/getting-started/ent-profile.md +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -36,7 +36,7 @@ The `ent profile` command is available to manage and switch between the configur ## Configuration Management -The output of `ent config` is a key-value archive of configuration settings related to the current profile. The following commands and keys especially notable. +The output of `ent config` is a key-value archive of configuration settings related to the current profile. The following commands and definitions are especially useful. ### Commands From 0e0a336f17b5b87de4dd33c53ef16873e5835a3f Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Mon, 25 Jul 2022 13:50:30 -0500 Subject: [PATCH 09/34] ENDOC-522 review edits --- .../next/docs/getting-started/entando-cli.md | 31 +++++++++---------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/entando-cli.md b/vuepress/docs/next/docs/getting-started/entando-cli.md index 4ff4e9afd0..aada80d3e2 100644 --- a/vuepress/docs/next/docs/getting-started/entando-cli.md +++ b/vuepress/docs/next/docs/getting-started/entando-cli.md @@ -4,7 +4,7 @@ sidebarDepth: 1 # Entando CLI -The Entando Command Line Interface (CLI), **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 overview, and a few operations to start using the ent tool. +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) @@ -15,27 +15,26 @@ For specific topics, follow these links: ### Prerequisites -The basic requirements for the CLI vary depending on the type of developer tasks as shown here. Ent is able to install secondary dependencies using the `ent check-env` command as described [here](#check-the-environment). +The basic requirements for the CLI vary depending on the type of developer tasks, as shown in the table below. The ent tool can install secondary dependencies using the `ent check-env` command as described [here](#check-the-environment). | Category | Prerequisite | :- | :- |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 (or organization) Docker images +| | a Docker Hub account for Docker images | Deploy an Entando Bundle | a Kubernetes cluster with admin access or a shared remote cluster ->TIP >The automatic option in [Getting Started](../getting-started/) will install the CLI along with a quickstart Entando Application. ## Install the CLI -Install the current offical release of the CLI with the following command: +Install the current official release of the CLI with the following command: ``` bash curl -L https://get.entando.org/cli | bash ``` -## Commands Overview -Use `ent help` to review the list of available commands. +## Command List +Use `ent help` to review the list of available commands.\ Use `ent COMMAND --help` to see the details for each command. ``` ~~~~~~~~~~~~~~~~~~~ @@ -51,18 +50,17 @@ ent [command] [subcommand] [name] [flags] > ent Commands: - app => Helper for managing an Entando App - app-info => Displays information about an Entando App - - bundle => Helper for managing bundle functions. See below for more details + - bundle => Helper module for managing bundle functions. (See below for more details) + - bundler => export of resources from a running instance for v1 bundles only - check-env => Checks the environment for required dependencies and settings - diag => Runs diagnostics and aggregates the related info in a .tgz file - ent => Helper for managing the local ent installations - ecr => Helper for managing the ECR - help => Help information - - host => Helper for managing the system that hosts the quickstart VM - - jhipster (not there) + - jhipster => wrapper for the ent installation of JHipster - kubectl => Helper for using kubectl in ent managed scenarios - - node-cmd-wrapper => wrapper of node commands - - pod => Displays information related to a set of pods - - prj => Helper for managing Entando bundle projects + - pod => Displays information related to a set of pods + - prj => Helper for managing Entando bundle projects - profile => Helper for managing an Entando App - quickstart => Helper for installing Entando instances locally - run-tests => Runs the internal tests @@ -105,21 +103,22 @@ COMMANDS ``` ### Check the Environment -The `check-env` command verifies the presence of required dependencies and the appropriate versions for your Entando instance, automatically installing dependencies with developer guidance. +The `check-env` command verifies the presence of dependencies and versions for your Entando instance, automatically installing dependencies with developer approval. ``` ent check-env develop ``` ### Update the CLI -To update ent to the latest version. Run `ent check-env develop` after all updates to check dependecies. +To update ent to the latest version and check for dependencies: ``` sh bash <(curl -L "https://get.entando.org/cli") --update +ent check-env develop ``` >Alternatively, to perform a clean install, delete the `~/.entando` directory with `rm -rf ~/.entando`. Then reinstall the CLI with the instructions above. This will also remove the private copies of JHipster, Entando Blueprint, etc. ### Customize Quickstart -The `ent quickstart` command supports parameters to customize your quickstart environment. These options allow you to modify specific properties of your VM, installation versions and databases. +The `ent quickstart` command allows parameters that customize your quickstart environment. These options allow you to modify specific properties of your VM, installation versions and databases. |Operation |Syntax|Description| |:--|:--|:--| From 8b13a7404fd78dfcfbc10a6b57bec96ebbcb7701 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Mon, 25 Jul 2022 14:42:23 -0700 Subject: [PATCH 10/34] ENDOC-523 Diagnostics page + fix profile table headers --- .../next/docs/getting-started/ent-diag.md | 23 +++++++++++++++++++ .../next/docs/getting-started/ent-profile.md | 6 ++--- 2 files changed, 26 insertions(+), 3 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md index 52d668bdd0..74499cabc7 100644 --- a/vuepress/docs/next/docs/getting-started/ent-diag.md +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -2,3 +2,26 @@ sidebarDepth: 1 --- +# Diagnostics and Troubleshooting + +Diagnostic information is critical to analysis and troubleshooting, and the Entando CLI (ent) is a useful tool for debugging issues with an Entando instance. The [Getting Started](../../docs/getting-started/README.md) guide includes steps to install ent in a Multipass VM. The following commands can be run from this VM for insight into an Entando Application. + +| 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 diag` | Run diagnostics on the pods currently in an Entando namespace and prepare a diagnostic tar.gz +| `ent pod grep --all "error\|fail"` | Locate error messages within EntandoApp pods + +The command `ent diag` is a superset of 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" +``` + +::: tip +To resolve the error "Unable to extract the application client secret": + +- Verify that the current profile namespace and application name are correct and match the output of `ent status` +- Assign the appropriate namespace and application name via `ent appname YOUR-APPNAME` and `ent namespace YOUR-NAMESPACE` +::: \ No newline at end of file diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md index 9ebb49fe8a..446dd06bc1 100644 --- a/vuepress/docs/next/docs/getting-started/ent-profile.md +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -15,7 +15,7 @@ Common operations associated with profile management are detailed below. The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional information. -| Command | Definition +| Command | Description | :- | :- | `ent status` | Returns current connection and profile information | `ent pro new [profileName] [EntandoAppName] [namespace]` | Create and switch to a new profile @@ -40,7 +40,7 @@ The output of `ent config` is a key-value archive of configuration settings rela ### Commands -| Command | Definition +| Command | Description | :- | :- | `ent config --print` | Print the current config archive | `ent config --edit` | Interactively edit a config archive @@ -50,7 +50,7 @@ The output of `ent config` is a key-value archive of configuration settings rela ### Keys -| Key | Definition +| Key | Description |---|--- | ENTANDO_NAMESPACE | Stores the fallback namespace used by explicit or implicit runs of `ent kubectl` | ENTANDO_APPNAME | Stores the Entando Application name related to the current profile From d0344e343af4d2938fe4d280ee0118ebdd9afb4b Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 26 Jul 2022 14:38:32 -0700 Subject: [PATCH 11/34] ENDOC-524 --- .../docs/next/docs/getting-started/ent-api.md | 68 +++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md index fd40910d9e..4e9aa4762b 100644 --- a/vuepress/docs/next/docs/getting-started/ent-api.md +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -1,4 +1,72 @@ +--- +sidebarDepth: 1 +--- +# Overview +An API claim informs the Entando Platform that a microfrontend (MFE) or microservice (MS) intends to use the API of another microservice. This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. +## Internal vs. External API Claim + +An MFE can initiate both internal and external API claims. An internal API claim specifies an MS API existing in the same bundle as the MFE, while an external API claim specifies the MS API of another bundle. + +The structure of internal and external API claims are as follows: + +**Internal API claim** +``` json +{ + "name": "int-api", + "type": "internal", + "serviceName": "int-ms" +} +``` +**External API claim** +``` json +{ + "name": "ext-api", + "type": "external", + "serviceName": "ext-ms", + "bundle": "registry.hub.docker.com/my-org/my-entando-bundle" +} +``` + +## API Claim Commands + +Common operations associated with API claims are detailed below. + +The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional information. + +| Command | Description +| :- | :- +| `api add [mfe-name] [claim-name]` | Add an internal API claim to an MFE +| `api add-ext [mfe-name] [claim-name]` | Add an external API claim to an MFE +| `api rm [mfe-name] [claim-name]` | Remove an API claim from an MFE + +**Command details:** +- `api add` supports the following options: + - `service-name`: The name of a microservice in the same bundle as the micro frontend + - `service-url`: The URL of a microservice deployed in the local environment + +- `api add-ext` supports the following options: + - `bundle`: The external bundle URL + - `service-name`: The name of a microservice in the external bundle. If `service-name` is not set, `api add-ext` will initiate an interactive mode where the user can select from available bundles and microservices. + +## API Claim YAML Descriptor Mapping + +When the YAML descriptor of a micro frontend is generated (i.e. via the `pack` command), the API claim mapping is similar to the following: + +``` yaml +apiClaims: + - name: int-api + type: internal + serviceName: int-ms + - name: ext-api + type: external + bundle: registry.hub.docker.com/cecchisandrone/entando-simple-bundle + serviceName: ext-ms +``` + +- `name` and `type` correspond to the same fields in the API claim source descriptor +- `pluginName` corresponds to `serviceName` +- `bundleId` is a generated ID derived from the bundle \ No newline at end of file From 69b66a31eda68f8d5f1ad121a8399dd2e152638d Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 26 Jul 2022 16:55:15 -0700 Subject: [PATCH 12/34] ENDOC-524 Fix egregious errors --- vuepress/docs/next/docs/getting-started/ent-api.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md index 4e9aa4762b..e3e1c49818 100644 --- a/vuepress/docs/next/docs/getting-started/ent-api.md +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -35,13 +35,11 @@ The structure of internal and external API claims are as follows: Common operations associated with API claims are detailed below. -The `ent profile` command is available to manage and switch between the configurations of different Entando instances. Refer to `ent profile first-use-readme` for additional information. - | Command | Description | :- | :- -| `api add [mfe-name] [claim-name]` | Add an internal API claim to an MFE -| `api add-ext [mfe-name] [claim-name]` | Add an external API claim to an MFE -| `api rm [mfe-name] [claim-name]` | Remove an API claim from an MFE +| `ent bundle api add [mfe-name] [claim-name]` | Add an internal API claim to an MFE +| `ent bundle api add-ext [mfe-name] [claim-name]` | Add an external API claim to an MFE +| `ent bundle api rm [mfe-name] [claim-name]` | Remove an API claim from an MFE **Command details:** - `api add` supports the following options: From 2f8ea11fda3055575de35144e18eaf663c0fb121 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 28 Jul 2022 09:20:44 -0500 Subject: [PATCH 13/34] ENDOC-522 review edits re:v1 --- .../docs/next/docs/getting-started/entando-cli.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/entando-cli.md b/vuepress/docs/next/docs/getting-started/entando-cli.md index aada80d3e2..6bd9cb08c2 100644 --- a/vuepress/docs/next/docs/getting-started/entando-cli.md +++ b/vuepress/docs/next/docs/getting-started/entando-cli.md @@ -44,14 +44,12 @@ Use `ent COMMAND --help` to see the details for each command. > Essentials: - Activate using: ~/.entando/ent/v7.0.0/cli/v7.0.0/activate - Deactivate using: ~/.entando/ent/v7.0.0/cli/v7.0.0/deactivate -> Syntax: -ent [command] [subcommand] [name] [flags] > ent Commands: - app => Helper for managing an Entando App - app-info => Displays information about an Entando App - - bundle => Helper module for managing bundle functions. (See below for more details) - - bundler => export of resources from a running instance for v1 bundles only + - bundle => Helper module for managing Docker-based (v5) bundles. (See below for more details) + - bundler => Export resources from a running instance as a git-based (v1) bundle. - check-env => Checks the environment for required dependencies and settings - diag => Runs diagnostics and aggregates the related info in a .tgz file - ent => Helper for managing the local ent installations @@ -60,7 +58,7 @@ ent [command] [subcommand] [name] [flags] - jhipster => wrapper for the ent installation of JHipster - kubectl => Helper for using kubectl in ent managed scenarios - pod => Displays information related to a set of pods - - prj => Helper for managing Entando bundle projects + - prj => Helper for managing Entando git-based (v1) bundle projects - profile => Helper for managing an Entando App - quickstart => Helper for installing Entando instances locally - run-tests => Runs the internal tests @@ -72,7 +70,8 @@ ent [command] [subcommand] [name] [flags] > ⚠ RECOMMENDED FIRST STEP ⚠ : - Check the dependencies (ent check-env --help) ``` -** New for version 7.1 ** +**New for Entando 7.1** + ``` ~~~~~~~~~~~~~~~~~~~ ent bundle CLI @@ -81,7 +80,7 @@ VERSION @entando/entando-bundle-cli/0.0.1-ENG-3939-PR-101 darwin-x64 node-v14.19.0 USAGE - $ ent bundle [COMMAND] + $ ent bundle COMMAND TOPICS api Manage API claims @@ -103,7 +102,7 @@ COMMANDS ``` ### Check the Environment -The `check-env` command verifies the presence of dependencies and versions for your Entando instance, automatically installing dependencies with developer approval. +The `check-env` command checks the dependencies and their versions for your Entando instance, automatically installing them with developer approval. ``` ent check-env develop ``` From aa7d858f2ec0df89b69089b3b5e4291b19f2c4ec Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Thu, 28 Jul 2022 12:30:18 -0700 Subject: [PATCH 14/34] ENDOC-525 --- .../docs/next/docs/getting-started/ent-svc.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index b497c4f967..46ecab6278 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -1,3 +1,61 @@ --- sidebarDepth: 1 --- + +# Auxiliary Services + +The following sections discuss auxiliary services and commands. + +## Services + +When the Entando Bundle CLI enables a service, a default auxiliary configuration is generated and stored as a Docker Compose YAML file in the bundle's 'svc' folder. Three services are available out of the box: `mysql`, `postgresql` and `keycloak`. + +- `mysql` and `postgresql` obey the same naming convention + - The username and password are derived from the bundle name, e.g. YOUR-BUNDLE has the username YOUR-BUNDLE-USER and the password YOUR-BUNDLE-PASSWORD + - A database is automatically created and given the bundle name, e.g. YOUR-BUNDLE + +- `keycloak` contains the Entando-related configuration + - The `keycloak` realm name is 'entando-dev' + - The console is accessible at *http://localhost:9080* with username: *admin*, password: *admin* + - All roles and permissions are preset, based on the Keycloak realm-config file + - The `keycloak.yaml`, realm-config and user config files are located in the 'keycloak' folder inside 'svc' + +A custom service can be added to a bundle's 'svc' folder as a Docker Compose YAML file. The file and service must have the same name, e.g. if the service filename is `mysql.yml`, then the service name must be `mysql`: + +``` yaml +version: '3.7' + +services: + # since filename is mysql.yml, service name is 'mysql' as declared below: + mysql: + image: mysql + ... +``` + +## Commands + +Use `ent bundle svc` to enable, disable, start, stop, restart, print the logs of, or list services. Services must be formatted as Docker Compose YAML files in the 'svc' bundle folder. + +To run auxiliary operations, a service must be enabled. Enabled services are listed under the 'svc' attribute of the bundle descriptor, `entando.json`. Common auxiliary service commands are detailed below. + +| Command | Description +| :- | :- +| `ent bundle svc enable ` | Adds the service(s) to the bundle’s auxiliary services +| `ent bundle svc disable ` | Removes the service(s) from the bundle’s auxiliary services +| `ent bundle svc start ` | Starts the enabled service(s) +| `ent bundle svc stop ` | Stops the enabled service(s) +| `ent bundle svc restart ` | Restarts the enabled service(s) +| `ent bundle svc logs ` | Prints the enabled service log(s) +| `ent bundle svc list` | Lists all enabled services + +**Command details:** + +- `svc enable`: Adds the service(s) to the 'svc' attribute of the bundle descriptor + +- `svc disable`: Removes the service(s) from the 'svc' attribute of the bundle descriptor + +- `svc logs`: The log of a running service will continue to update until exited via `Ctrl+C` + +- `svc list`: Include the option `--available` to list all services located in the 'svc' bundle folder + +- Auxiliary commands can operate on multiple services by listing each service name as an argument, e.g. `ent bundle svc start service_1 service_2`. The option `--all` applies the command to all enabled bundle services. \ No newline at end of file From 044e4f7f3632d339577a966b87b379d0bcd33317 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Thu, 28 Jul 2022 12:36:24 -0700 Subject: [PATCH 15/34] ENDOC-523 --- vuepress/docs/next/docs/getting-started/ent-diag.md | 11 ++--------- 1 file changed, 2 insertions(+), 9 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md index 74499cabc7..7ee646f899 100644 --- a/vuepress/docs/next/docs/getting-started/ent-diag.md +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -13,15 +13,8 @@ Diagnostic information is critical to analysis and troubleshooting, and the Enta | `ent diag` | Run diagnostics on the pods currently in an Entando namespace and prepare a diagnostic tar.gz | `ent pod grep --all "error\|fail"` | Locate error messages within EntandoApp pods -The command `ent diag` is a superset of 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: +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" -``` - -::: tip -To resolve the error "Unable to extract the application client secret": - -- Verify that the current profile namespace and application name are correct and match the output of `ent status` -- Assign the appropriate namespace and application name via `ent appname YOUR-APPNAME` and `ent namespace YOUR-NAMESPACE` -::: \ No newline at end of file +``` \ No newline at end of file From 4bbd53cf605e99598a5f1107c856d3f93daf112a Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 28 Jul 2022 15:56:01 -0500 Subject: [PATCH 16/34] ENDOC-513 new bundle cli page --- .../next/docs/getting-started/ent-bundle.md | 176 +++++++++++++++++- 1 file changed, 175 insertions(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index b497c4f967..2383f2ec8f 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -1,3 +1,177 @@ --- -sidebarDepth: 1 +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, whether it comes with a single component or many, and packages them into convenient recognizable bundles that can be inserted into any Entando Application. This modular approach takes advantage of a single project descriptor and repository, along with centralized [management of APIs](ent-api.md) and [services for DB and Keycloak](ent-svc.md). + +This document covers ent bundle operations and how it manages the lifecycle of a bundle, organized by the steps required. + +1. [Initialization](#initialization) +2. [Build](#build) +3. [Run](#run) +4. [Package](#package) +5. [Publish](#publish) +6. [ECR Deploy](#ecr-bundle-commands) + +### Bundle Lifecycle Overview +A single JSON descriptor file can define the parameters of an Entando project, but the life of an Entando Bundle begins at initialization. The ent init step sets up the structure and scaffolding needed for a new bundle. This tool allows a project to be intialized directly from the Entando Hub, speeding up the development process. The second step builds the project components for the micro frontends (MFE) and microservices (MS), whether you have a single component or many MSs and MFEs. They are built in parallel, using processes that are dependent on your stack, and given version numbers filtered by type and name. + +The next step runs the components, processed in the same way by type and name, resulting in log files for each. The ent pack step generates the artifacts and builds the Docker images. A single Docker image is built for the bundle and all its microservices. Then Docker images are built for each micro frontend. Finally, these images are published to a Docker repository. + +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] [arguments]` +| 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 +|`ms`|`add`| Add ms project components +| | `init` | Init MS with scaffolding +| | `rm` | Remove a MS project component +|`mfe` | `add` | Add a MFE project component +| | `init` | Init with scaffolding +| | `rm` | Remove MFE project component +|`run`|| Run bundle components +|`pack`||Create distribution artifacts (Docker images) +|`publish`||Publish Docker images to a Docker registry + + +## Initialization + +| Command | Description +|:--|:-- +|`ent bundle init [name]` |Initialize a new project with the default structure and files +|`ent bundle init [name] --from-hub`| Initialize a bundle from an Entando Hub + +#### Command Details +* `ent bundle init [name] --from-hub`: Utilize an existing bundle from an Entando Hub to jump start your project. The ent bundle CLI will pull the package and rebuild the structure as needed, ready for customization. + +## Build + +| Command| Descriptions +|:--|:-- +|`ent bundle build [component-name]` | Build a single component +|`ent bundle build [mfe-1] [ms-2]...`| Build every the component passed as arguments +|`ent bundle build --all`|Build all the components in the project +|`ent bundle build --all-ms`|Build all microservices| +|`ent bundle build --all-mfe`|Build all the microfrontend| + +#### 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, npm build will be performed for a React MFE. A log file is generated for each component inside the .entando/logs directory for your project. + +## Run +| Command| Descriptions +|:--|:-- +|`ent bundle run [component-name]` | Locally run your single component +|`ent bundle run [mfe-1] [ms-2]...`| Locally run all the components passed as arguments +|`ent bundle run --all`| Locally run all the components in the bundle +|`ent bundle run --all-ms`| Locally run the MSs in the bundle +|`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. + +## Package +| Command| Descriptions +|:--|:-- +|`ent bundle pack`|Generate the bundle artifacts, and the bundle Docker image and MS images +|`ent bundle pack --org [organization]`|Generate the bundle artifacts, passing the organization name to the Docker Hub| +|`ent bundle pack --file [my-dockerfile]`|Use a custom Dockerfile for your bundle | + +#### Command Details +* `ent bundle pack`: For the MFEs and MSs, the generated artifacts are located inside each component's folders. Their format depends on the component type. For instance, a React micro frontend may result in HTML, JavaScript and CSS files. + +When artifact generation is complete, microservices Docker images are built, executing the docker build command using the Dockerfile located in each microservice folder. If the Dockerfile is missing, the pack command exits with failure. + +** Should we include info about where yaml descriptors are located, how they are produced from entando.json, pom.xml or package.json, or how to see the outputs for the MFE in the DEBUG mode + +## Publish +| Command| Descriptions +|:--|:-- +|ent bundle publish| Publish your Docker images to index.docker.io (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| + +#### Command Details +* `ent bundle publish --org`: If the organization name has changed, the Docker tag command can be used to create new image tags for the new name to be stored in .entando/config.json. + + docker tag OLD-ORG-NAME/YOUR-IMAGE:tag NEW-ORG-NAME/YOUR-IMAGE:tag + +* `ent bundle publish --registry` + 1. A specific Docker registry can be used but it must be authenticated by using the --config flag on the login command. + ``` + docker --config path/to/.docker login YOUR-REGISTRY + ``` + This is how the authentication context used by ent is kept separated from the default authentication context for the user. Credentials will be stored unencrypted in `path/to/.docker/config.json` unless a credentials helper is used. + + 2. If you are using a custom registry, images need to be renamed, prepending the custom registry name to the image names using this Docker command: + ``` + docker tag YOUR-ORG-NAME/YOUR-IMAGE-NAME:tag YOUR-REGISTRY/YOUR-ORG-NAME/YOUR-IMAGE-NAME:tag + ``` + + ** 3. is this useful to include >>>>>> The path to the config file is mapped by the environment variable ENTANDO_CLI_DOCKER_CONFIG_PATH. + +## ECR Bundle 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 list`| Display the list of bundles associated with the current profile| +|`ent ecr deploy`| Generate the CR and deploy it to the current profile | +|`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 + + +#### Command Details +* `get-bundle-id` and `get-plugin-id`: Entando uses a unique identifier for your bundle as a way to provide customization parameters and added security controls around bundle-specific resources. A unique identifier is also generated for each microservice plugin in your project. + +## Git-based Bundle Commands +These ent CLI commands are required when using a Git-based (v1) bundle. +| Command| Descriptions +|:--|:-- +|`ent prj build`|Build the project components| +|`ent prj pbs-init` | Initialize the bundle directory +|`ent prj pbs-publish`| Publish the built artifacts to GitHub and Docker Hub +|`ent prj deploy`| Deploy the bundle into the ECR| +|`ent prj install`| Install the bundle into Entando| +|`ent prj install --conflict-strategy=OVERRIDE`|to adopt a strategy for installed bundles +|`ent prj ext-keycloak start`|Initialize Keycloak to leverage Docker Compose| +|`ent prj be-test-run`|Initialize backend microservices| +|`ent prj fe-test-run`|Initialize one or more frontend widgets, each from its own shell| +|`ent prj be-log`| Fetch logs from bundle plugins| +|`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 bundler from-git`|Generate a custom resource for publication or exporting from a Git Repository| +|`ent bundler from-env`|Generate a custom resource from an existing environment into the current or selected location| + +#### 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 your bundle as a way to provide customization parameters and added security controls around 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 template for building a new application. + + * An `env.json` file to configure the application URLs and client credentials must live in the directory from which the bundler is run. For example: + ``` json + { + "coreBaseApi": "http://YOUR-DOMAIN-OR-IP/entando-de-app", + "componentManagerApi": "http://YOUR-DOMAIN-OR-IP/digital-exchange", + "clientId": "YOUR-CLIENT-ID", + "clientSecret": "YOUR-CLIENT-SECRET" + } + ``` + Instructions to export a bundle, including how to configure `env.json`, can be found in the [Export and Publish a Bundle tutorial](../../tutorials/create/pb/export-bundle-from-application.md). + * Extraction Error: If you receive an `Unable to extract the application client secret` error message: + 1. Verify that the current profile namespace and application name are correct and match the output of the following command: + ``` sh + ent status + ``` + 2. Assign the appropriate namespace and application name: + ``` sh + 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. From e54e22815fa0f51b29db8fe6130e425742f4b27d Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Fri, 29 Jul 2022 12:51:10 -0700 Subject: [PATCH 17/34] ENDOC-524 minor fix --- vuepress/docs/next/docs/getting-started/ent-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md index e3e1c49818..cfe361df3b 100644 --- a/vuepress/docs/next/docs/getting-started/ent-api.md +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -5,7 +5,7 @@ sidebarDepth: 1 # Overview -An API claim informs the Entando Platform that a microfrontend (MFE) or microservice (MS) intends to use the API of another microservice. This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. +An API claim informs the Entando Platform that a micro frontend (MFE) or microservice (MS) intends to use the API of another microservice. This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. ## Internal vs. External API Claim From 3d5a0fa0d5ccfe25d5908e97d4f307dd9adb327f Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Fri, 29 Jul 2022 15:30:03 -0700 Subject: [PATCH 18/34] ENDOC-525 Minor fixes --- vuepress/docs/next/docs/getting-started/ent-svc.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index 46ecab6278..facad9c8d4 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -14,7 +14,7 @@ When the Entando Bundle CLI enables a service, a default auxiliary configuration - The username and password are derived from the bundle name, e.g. YOUR-BUNDLE has the username YOUR-BUNDLE-USER and the password YOUR-BUNDLE-PASSWORD - A database is automatically created and given the bundle name, e.g. YOUR-BUNDLE -- `keycloak` contains the Entando-related configuration +- `keycloak` configures authentication for Entando - The `keycloak` realm name is 'entando-dev' - The console is accessible at *http://localhost:9080* with username: *admin*, password: *admin* - All roles and permissions are preset, based on the Keycloak realm-config file @@ -50,10 +50,6 @@ To run auxiliary operations, a service must be enabled. Enabled services are lis **Command details:** -- `svc enable`: Adds the service(s) to the 'svc' attribute of the bundle descriptor - -- `svc disable`: Removes the service(s) from the 'svc' attribute of the bundle descriptor - - `svc logs`: The log of a running service will continue to update until exited via `Ctrl+C` - `svc list`: Include the option `--available` to list all services located in the 'svc' bundle folder From 9e486f152dbd2c324458712ec4ef31bf72716739 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Sat, 30 Jul 2022 19:28:34 -0700 Subject: [PATCH 19/34] ENDOC-525 Introduce aux services --- vuepress/docs/next/docs/getting-started/ent-svc.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index facad9c8d4..a1d07ce2d3 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -4,7 +4,9 @@ sidebarDepth: 1 # Auxiliary Services -The following sections discuss auxiliary services and commands. +Auxiliary services extend the capabilities of a local development environment. Kubernetes can be configured to point to externally managed services, such as MySQL or PostgreSQL, or services are provided by the platform (e.g. Keycloak or RedHat SSO). + +The following sections describe how Entando supports and implements auxiliary services. ## Services From 55c96a832fd7225540f05b7c17488360ae2c6e1b Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Mon, 1 Aug 2022 09:21:23 -0500 Subject: [PATCH 20/34] ENDOC-513 zonia edits --- .../next/docs/getting-started/ent-bundle.md | 93 ++++++++----------- 1 file changed, 38 insertions(+), 55 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index 2383f2ec8f..f812516753 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -3,9 +3,9 @@ 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, whether it comes with a single component or many, and packages them into convenient recognizable bundles that can be inserted into any Entando Application. This modular approach takes advantage of a single project descriptor and repository, along with centralized [management of APIs](ent-api.md) and [services for DB and Keycloak](ent-svc.md). +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 the lifecycle of a bundle, organized by the steps required. +This document covers `ent bundle` operations and how it manages a project. 1. [Initialization](#initialization) 2. [Build](#build) @@ -14,30 +14,34 @@ This document covers ent bundle operations and how it manages the lifecycle of a 5. [Publish](#publish) 6. [ECR Deploy](#ecr-bundle-commands) -### Bundle Lifecycle Overview -A single JSON descriptor file can define the parameters of an Entando project, but the life of an Entando Bundle begins at initialization. The ent init step sets up the structure and scaffolding needed for a new bundle. This tool allows a project to be intialized directly from the Entando Hub, speeding up the development process. The second step builds the project components for the micro frontends (MFE) and microservices (MS), whether you have a single component or many MSs and MFEs. They are built in parallel, using processes that are dependent on your stack, and given version numbers filtered by type and name. +### Bundle Development Overview +A single JSON descriptor file works as the manifest for an Entando project to be converted into a reusable bundle. The process starts with the initialization step which +sets up the structure and scaffolding needed for a new project. Alternatively, the ent tool allows a bundle to be initialized directly from the Entando Hub, speeding up the development process. -The next step runs the components, processed in the same way by type and name, resulting in log files for each. The ent pack step generates the artifacts and builds the Docker images. A single Docker image is built for the bundle and all its microservices. Then Docker images are built for each micro frontend. Finally, these images are published to a Docker repository. +With the structure set up, ent builds the project components for the micro frontends (MFEs) and microservices (MS). They are built in parallel, using processes that are dependent on the stack, filtered by type and name and given version numbers. + +The next step runs the components locally, resulting in log files in each of the component's directories. + +The `ent pack` step generates the artifacts and builds the Docker images. A single image is created for the bundle and all micro frontends while each microservice gets its own image. Finally, these are published to a Docker repository. 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] [arguments]` +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 -|`ms`|`add`| Add ms project components -| | `init` | Init MS with scaffolding -| | `rm` | Remove a MS project component -|`mfe` | `add` | Add a MFE project component -| | `init` | Init with scaffolding +|`ms`|`add`| Add MS project components +| | `init` | Initialize MS with scaffolding +| | `rm` | Remove an MS project component +|`mfe` | `add` | Add an MFE project component +| | `init` | Initialize MFE with scaffolding | | `rm` | Remove MFE project component |`run`|| Run bundle components |`pack`||Create distribution artifacts (Docker images) -|`publish`||Publish Docker images to a Docker registry - +|`publish`||Publish images to a Docker registry ## Initialization @@ -47,73 +51,52 @@ syntax: `ent bundle [commands] [subcommand] [arguments]` |`ent bundle init [name] --from-hub`| Initialize a bundle from an Entando Hub #### Command Details -* `ent bundle init [name] --from-hub`: Utilize an existing bundle from an Entando Hub to jump start your project. The ent bundle CLI will pull the package and rebuild the structure as needed, ready for customization. +* `ent bundle init [name] --from-hub`: Utilize an existing bundle from an Entando Hub to jumpstart your project. The ent bundle tool will pull the package and rebuild the structure as needed, ready for customization. ## Build | Command| Descriptions |:--|:-- |`ent bundle build [component-name]` | Build a single component -|`ent bundle build [mfe-1] [ms-2]...`| Build every the component passed as arguments +|`ent bundle build [mfe-1] [ms-2]...`| Build one or more named components |`ent bundle build --all`|Build all the components in the project |`ent bundle build --all-ms`|Build all microservices| -|`ent bundle build --all-mfe`|Build all the microfrontend| +|`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, npm build will be performed for a React MFE. A 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 `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. ## Run | Command| Descriptions |:--|:-- |`ent bundle run [component-name]` | Locally run your single component -|`ent bundle run [mfe-1] [ms-2]...`| Locally run all the components passed as arguments +|`ent bundle run [mfe-1] [ms-2]...`| Locally run one or more named components passed as arguments |`ent bundle run --all`| Locally run all the components in the bundle -|`ent bundle run --all-ms`| Locally run the MSs in the bundle +|`ent bundle run --all-ms`| Locally run the microservices in the bundle |`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 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. ## Package | Command| Descriptions |:--|:-- -|`ent bundle pack`|Generate the bundle artifacts, and the bundle Docker image and MS images -|`ent bundle pack --org [organization]`|Generate the bundle artifacts, passing the organization name to the Docker Hub| +|`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 --file [my-dockerfile]`|Use a custom Dockerfile for your bundle | #### Command Details -* `ent bundle pack`: For the MFEs and MSs, the generated artifacts are located inside each component's folders. Their format depends on the component type. For instance, a React micro frontend may result in HTML, JavaScript and CSS files. +* `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. -When artifact generation is complete, microservices Docker images are built, executing the docker build command using the Dockerfile located in each microservice folder. If the Dockerfile is missing, the pack command exits with failure. - -** Should we include info about where yaml descriptors are located, how they are produced from entando.json, pom.xml or package.json, or how to see the outputs for the MFE in the DEBUG mode +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 index.docker.io (default) +|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| -#### Command Details -* `ent bundle publish --org`: If the organization name has changed, the Docker tag command can be used to create new image tags for the new name to be stored in .entando/config.json. - - docker tag OLD-ORG-NAME/YOUR-IMAGE:tag NEW-ORG-NAME/YOUR-IMAGE:tag - -* `ent bundle publish --registry` - 1. A specific Docker registry can be used but it must be authenticated by using the --config flag on the login command. - ``` - docker --config path/to/.docker login YOUR-REGISTRY - ``` - This is how the authentication context used by ent is kept separated from the default authentication context for the user. Credentials will be stored unencrypted in `path/to/.docker/config.json` unless a credentials helper is used. - - 2. If you are using a custom registry, images need to be renamed, prepending the custom registry name to the image names using this Docker command: - ``` - docker tag YOUR-ORG-NAME/YOUR-IMAGE-NAME:tag YOUR-REGISTRY/YOUR-ORG-NAME/YOUR-IMAGE-NAME:tag - ``` - - ** 3. is this useful to include >>>>>> The path to the config file is mapped by the environment variable ENTANDO_CLI_DOCKER_CONFIG_PATH. - ## ECR Bundle Commands Entando provides a series of `ent ecr` commands for managing bundle interactions with [the Entando Component Repository](../../docs/compose/ecr-overview.md) (ECR). @@ -126,31 +109,31 @@ Entando provides a series of `ent ecr` commands for managing bundle interactions #### Command Details -* `get-bundle-id` and `get-plugin-id`: Entando uses a unique identifier for your bundle as a way to provide customization parameters and added security controls around bundle-specific resources. A unique identifier is also generated for each microservice plugin in your project. +* `get-bundle-id` and `get-plugin-id`: Entando uses a unique identifier for your 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. ## Git-based Bundle Commands These ent CLI commands are required when using a Git-based (v1) bundle. | Command| Descriptions |:--|:-- -|`ent prj build`|Build the project components| +|`ent prj build`|Build project components| |`ent prj pbs-init` | Initialize the bundle directory -|`ent prj pbs-publish`| Publish the built artifacts to GitHub and Docker Hub +|`ent prj pbs-publish`| Publish the artifacts to GitHub and Docker Hub |`ent prj deploy`| Deploy the bundle into the ECR| |`ent prj install`| Install the bundle into Entando| -|`ent prj install --conflict-strategy=OVERRIDE`|to adopt a strategy for installed bundles -|`ent prj ext-keycloak start`|Initialize Keycloak to leverage Docker Compose| +|`ent prj install --conflict-strategy=OVERRIDE`|Adopt a strategy for conflict on installed bundles +|`ent prj ext-keycloak start`|Initialize Keycloak which leveverage Docker Compose| |`ent prj be-test-run`|Initialize backend microservices| |`ent prj fe-test-run`|Initialize one or more frontend widgets, each from its own shell| |`ent prj be-log`| Fetch logs from bundle plugins| |`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 bundler from-git`|Generate a custom resource for publication or exporting from a Git Repository| -|`ent bundler from-env`|Generate a custom resource from an existing environment into the current or selected location| +|`ent bundler from-git`|Generate a custom resource for publication or exporting from a Git repository| +|`ent bundler from-env`|Generate a custom resource from an existing environment for the current or selected location| #### 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 your bundle as a way to provide customization parameters and added security controls around 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-id`: Entando uses a unique identifier for your 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 template for building a new application. From 2ca54cb31474f48109c0e7e412e7648b656c1642 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Mon, 1 Aug 2022 09:03:21 -0700 Subject: [PATCH 21/34] ENDOC-525 Revise intro --- vuepress/docs/next/docs/getting-started/ent-svc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index a1d07ce2d3..c7a49ea413 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -4,7 +4,7 @@ sidebarDepth: 1 # Auxiliary Services -Auxiliary services extend the capabilities of a local development environment. Kubernetes can be configured to point to externally managed services, such as MySQL or PostgreSQL, or services are provided by the platform (e.g. Keycloak or RedHat SSO). +Auxiliary services add capabilities to a local environment to accelerate application development. This is in contrast to developing on Kubernetes, where the equivalent services are either provisioned by the Entando Platform or are externally managed and pointed to by the application. The following sections describe how Entando supports and implements auxiliary services. From 903f61a89cddaba0ba012c763b15d0c111834a39 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 2 Aug 2022 08:11:29 -0700 Subject: [PATCH 22/34] ENDOC-524 Level up --- .../docs/next/docs/getting-started/ent-api.md | 53 +++++++++++++------ 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md index cfe361df3b..9dc1d96d20 100644 --- a/vuepress/docs/next/docs/getting-started/ent-api.md +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -5,11 +5,11 @@ sidebarDepth: 1 # Overview -An API claim informs the Entando Platform that a micro frontend (MFE) or microservice (MS) intends to use the API of another microservice. This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. +An API claim informs the Entando Platform that a micro frontend (MFE) intends to use the API of a microservice (MS). This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. ## Internal vs. External API Claim -An MFE can initiate both internal and external API claims. An internal API claim specifies an MS API existing in the same bundle as the MFE, while an external API claim specifies the MS API of another bundle. +An MFE can initiate both internal and external API claims. An internal claim specifies an MS API in the same bundle as the MFE, while an external claim specifies the MS API of another bundle in the same Kubernetes namespace. The structure of internal and external API claims are as follows: @@ -33,7 +33,7 @@ The structure of internal and external API claims are as follows: ## API Claim Commands -Common operations associated with API claims are detailed below. +Common operations associated with API claims are detailed below. To execute `ent bundle api` subcommands, the user must be connected to a running Entando instance (via `ent attach`) or the CLI will generate an authentication error. | Command | Description | :- | :- @@ -50,21 +50,40 @@ Common operations associated with API claims are detailed below. - `bundle`: The external bundle URL - `service-name`: The name of a microservice in the external bundle. If `service-name` is not set, `api add-ext` will initiate an interactive mode where the user can select from available bundles and microservices. -## API Claim YAML Descriptor Mapping +- `api add-ext` requirements: + - Connection to an Entando instance + - The cluster contains the service specified in the API claim + - The external service has already been deployed -When the YAML descriptor of a micro frontend is generated (i.e. via the `pack` command), the API claim mapping is similar to the following: +- Executing `api add-ext` without flags: + - Returns the current instance + - Displays the instance's available services for interactive selection -``` yaml -apiClaims: - - name: int-api - type: internal - serviceName: int-ms - - name: ext-api - type: external - bundle: registry.hub.docker.com/cecchisandrone/entando-simple-bundle - serviceName: ext-ms +## Microservice URL Retrieval + +To render an MFE installed from a bundle, Entando injects a JSON object containing configuration details inside the "config" attribute of a custom HTML element, e.g. ``. + +**Installed Bundles** + +To retrieve the URL of an MS declared through an API claim, add `systemParams.api[claimName].url` to the MFE JavaScript code so it can access that element of the config object. The `claimName` was chosen by the user when the API claim was defined. + +Refer to the Entando demo bundles for alternative retrieval methods. These techniques are more robust and consider cases where the parent object is not defined. + +**Local Bundles** + +When testing an MFE locally, the MS URL can be retrieved from the `mfe-config.json` file in the "public" MFE folder, e.g: ``` +{ + "systemParams": { + "api": { + "my-api-claim": { + "url": "http://localhost:8082" + } + } + } +} +``` + +This file is not used outside of local testing. The configuration data of installed bundles are provided by the Entando instance. -- `name` and `type` correspond to the same fields in the API claim source descriptor -- `pluginName` corresponds to `serviceName` -- `bundleId` is a generated ID derived from the bundle \ No newline at end of file +The commands that add and remove API claims update `mfe-config.json` automatically. \ No newline at end of file From e0d016681369a8e50bc333b849900b37ef242932 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Tue, 2 Aug 2022 13:41:13 -0500 Subject: [PATCH 23/34] ENDOC-513 add ent ecr commands --- .../next/docs/getting-started/ent-bundle.md | 44 +++++++++++-------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index f812516753..e276e5044e 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -29,16 +29,16 @@ See [Build and Publish a Project Bundle](../../tutorials/create/pb/publish-proje ## 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 -|`ms`|`add`| Add MS project components -| | `init` | Initialize MS with scaffolding -| | `rm` | Remove an MS project component |`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 +| | `rm` | Remove an MS project component |`run`|| Run bundle components |`pack`||Create distribution artifacts (Docker images) |`publish`||Publish images to a Docker registry @@ -97,45 +97,51 @@ Once the artifacts are generated, Docker images for the microservices are built |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 Bundle Commands +## 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 list`| Display the list of bundles associated with the current profile| -|`ent ecr deploy`| Generate the CR and deploy it to the current profile | +|`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 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 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| +|`ent ecr uninstall`| Uninstall a bundle| #### Command Details -* `get-bundle-id` and `get-plugin-id`: Entando uses a unique identifier for your 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 ecr get-bundle-id` and `ent ecr get-plugin-id`: Entando uses a unique identifier for your 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 ecr 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. ## Git-based Bundle Commands These ent CLI commands are required when using a Git-based (v1) bundle. | Command| Descriptions |:--|:-- +|`ent bundler from-git`|Generate a CR for publication or exporting from a Git repository| +|`ent bundler from-env`|Generate a CR from an existing environment for the current or selected location| +|`ent prj be-log`| Fetch logs from bundle plugins| +|`ent prj be-test-run`|Initialize backend microservices| |`ent prj build`|Build project components| -|`ent prj pbs-init` | Initialize the bundle directory -|`ent prj pbs-publish`| Publish the artifacts to GitHub and Docker Hub |`ent prj deploy`| Deploy the bundle into the ECR| -|`ent prj install`| Install the bundle into Entando| -|`ent prj install --conflict-strategy=OVERRIDE`|Adopt a strategy for conflict on installed bundles -|`ent prj ext-keycloak start`|Initialize Keycloak which leveverage Docker Compose| -|`ent prj be-test-run`|Initialize backend microservices| +|`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 be-log`| Fetch logs from bundle plugins| |`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 bundler from-git`|Generate a custom resource for publication or exporting from a Git repository| -|`ent bundler from-env`|Generate a custom resource from an existing environment for the current or selected location| +|`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 +|`ent prj pbs-publish`| Publish the artifacts to GitHub and Docker Hub #### 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 your 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 template for building a new application. +* `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. * An `env.json` file to configure the application URLs and client credentials must live in the directory from which the bundler is run. For example: ``` json From 6d5cbde7b45dee7d0e6f4995ccaa2c6688a6560f Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Tue, 2 Aug 2022 12:10:33 -0700 Subject: [PATCH 24/34] ENDOC-524 Final edits --- vuepress/docs/next/docs/getting-started/ent-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md index 9dc1d96d20..722a322b27 100644 --- a/vuepress/docs/next/docs/getting-started/ent-api.md +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -33,7 +33,7 @@ The structure of internal and external API claims are as follows: ## API Claim Commands -Common operations associated with API claims are detailed below. To execute `ent bundle api` subcommands, the user must be connected to a running Entando instance (via `ent attach`) or the CLI will generate an authentication error. +Common operations associated with API claims are detailed below. To execute `ent bundle api` subcommands, the user must be connected to a running Entando instance (via `ent attach-*`) or the CLI will generate an authentication error. | Command | Description | :- | :- @@ -67,7 +67,7 @@ To render an MFE installed from a bundle, Entando injects a JSON object containi To retrieve the URL of an MS declared through an API claim, add `systemParams.api[claimName].url` to the MFE JavaScript code so it can access that element of the config object. The `claimName` was chosen by the user when the API claim was defined. -Refer to the Entando demo bundles for alternative retrieval methods. These techniques are more robust and consider cases where the parent object is not defined. +Refer to the Entando demo bundles for alternative retrieval methods that are more robust and consider cases where the parent object is not defined. **Local Bundles** From 6bca6f2c702b28817b8aa274be09c66d536e27ec Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Tue, 2 Aug 2022 14:43:34 -0500 Subject: [PATCH 25/34] ENDOC-513 correct link --- vuepress/docs/next/docs/getting-started/ent-bundle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index e276e5044e..bca1315121 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -12,7 +12,7 @@ This document covers `ent bundle` operations and how it manages a project. 3. [Run](#run) 4. [Package](#package) 5. [Publish](#publish) -6. [ECR Deploy](#ecr-bundle-commands) +6. [ECR Deploy](#ecr-commands) ### Bundle Development Overview A single JSON descriptor file works as the manifest for an Entando project to be converted into a reusable bundle. The process starts with the initialization step which From 860cf55ae85980e251e474888e7c52f0a27d461c Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Tue, 2 Aug 2022 18:16:59 -0500 Subject: [PATCH 26/34] ENDOC-513 minor edit --- vuepress/docs/next/docs/getting-started/ent-bundle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-bundle.md b/vuepress/docs/next/docs/getting-started/ent-bundle.md index bca1315121..48746bdf9c 100644 --- a/vuepress/docs/next/docs/getting-started/ent-bundle.md +++ b/vuepress/docs/next/docs/getting-started/ent-bundle.md @@ -113,7 +113,7 @@ Entando provides a series of `ent ecr` commands for managing bundle interactions |`ent ecr uninstall`| Uninstall a bundle| #### Command Details -* `ent ecr get-bundle-id` and `ent ecr get-plugin-id`: Entando uses a unique identifier for your 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 ecr get-bundle-id` and `ent ecr 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 ecr 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. @@ -139,7 +139,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 your 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-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 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. From 796abf3eda6a62781659a6d41918e2ced6ddd26a Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Wed, 3 Aug 2022 14:21:03 -0500 Subject: [PATCH 27/34] ENDOC-535-ssl-note --- .../getting-started/openshift-install-by-operator.md | 8 ++++++++ .../getting-started/openshift-install-by-operator.md | 10 ++++++++++ 2 files changed, 18 insertions(+) diff --git a/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md b/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md index 815d890b5f..bd3a49d85f 100644 --- a/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md +++ b/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md @@ -140,6 +140,14 @@ Now let's create a new application similar to Scenario 3, but with the self-sign Once the deployment is complete, you can confirm that all routes use HTTPS with the self-signed certificate. You may still see security warnings in the browser. +#### Note: Multiple Certificate Chains +If you have multiple certificates to load into Openshift, you must pass each certificate with its own identifier. +```bash +ca0.crt: -\> a single ca certificate +ca1.crt: -\> another ca certificate +... +ca5.crt -\> last ca certificate +``` See the [Next Steps](#next-steps) below to continue your work with Entando. ## Next Steps diff --git a/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md b/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md index 815d890b5f..ffe37c6044 100644 --- a/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md +++ b/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md @@ -140,6 +140,16 @@ Now let's create a new application similar to Scenario 3, but with the self-sign Once the deployment is complete, you can confirm that all routes use HTTPS with the self-signed certificate. You may still see security warnings in the browser. +#### Note: Multiple Certificate Chains +If you have multiple certificates to load into Openshift, you must pass each certificate with its own identifier. +```bash +ca0.crt: -\> a single ca certificate +ca1.crt: -\> another ca certificate +... +ca5.crt -\> last ca certificate +``` + + See the [Next Steps](#next-steps) below to continue your work with Entando. ## Next Steps From 7e15298a8fd81e0a6aa2797ae839d5872526be46 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Wed, 3 Aug 2022 16:44:48 -0500 Subject: [PATCH 28/34] ENDOC-535-ssl-note review edit --- .../openshift-install-by-operator.md | 11 ++++++----- .../openshift-install-by-operator.md | 15 ++++++++------- 2 files changed, 14 insertions(+), 12 deletions(-) diff --git a/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md b/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md index bd3a49d85f..524c41fc11 100644 --- a/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md +++ b/vuepress/docs/next/tutorials/getting-started/openshift-install-by-operator.md @@ -117,6 +117,7 @@ type: kubernetes.io/tls Now create the `entando-ca-cert-secret` Secret, similar to what was done in Scenario 3, but this time using the self-signed certificate. 4. Go to `Workloads` → `Secrets` → `Create` and select `Key/value secret` + For multiple certificates, see note below on [Certificate Chains](#note-certificate-chains). 5. Set the `Secret Name`, e.g. `entando-ca-cert-secret` 6. Set the `Key`, e.g. `tls.crt` 7. Set the `Value` by clicking `Browse...` and loading the cert file from Step 1, e.g. `tls.crt` @@ -140,13 +141,13 @@ Now let's create a new application similar to Scenario 3, but with the self-sign Once the deployment is complete, you can confirm that all routes use HTTPS with the self-signed certificate. You may still see security warnings in the browser. -#### Note: Multiple Certificate Chains -If you have multiple certificates to load into Openshift, you must pass each certificate with its own identifier. +#### Note: Certificate Chains +If you have multiple certificates to load into OpenShift, you must pass each with its own identifier. ```bash -ca0.crt: -\> a single ca certificate -ca1.crt: -\> another ca certificate +ca0.crt: → a single CA certificate +ca1.crt: → another CA certificate ... -ca5.crt -\> last ca certificate +ca5.crt → last CA certificate ``` See the [Next Steps](#next-steps) below to continue your work with Entando. diff --git a/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md b/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md index ffe37c6044..c4b7a80a84 100644 --- a/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md +++ b/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md @@ -116,7 +116,9 @@ type: kubernetes.io/tls Now create the `entando-ca-cert-secret` Secret, similar to what was done in Scenario 3, but this time using the self-signed certificate. -4. Go to `Workloads` → `Secrets` → `Create` and select `Key/value secret` +4. Go to `Workloads` → `Secrets` → `Create` and select `Key/value secret`\ + For multiple certificates, see note below on [Certificate Chains](#note-certificate-chains). + 5. Set the `Secret Name`, e.g. `entando-ca-cert-secret` 6. Set the `Key`, e.g. `tls.crt` 7. Set the `Value` by clicking `Browse...` and loading the cert file from Step 1, e.g. `tls.crt` @@ -140,16 +142,15 @@ Now let's create a new application similar to Scenario 3, but with the self-sign Once the deployment is complete, you can confirm that all routes use HTTPS with the self-signed certificate. You may still see security warnings in the browser. -#### Note: Multiple Certificate Chains -If you have multiple certificates to load into Openshift, you must pass each certificate with its own identifier. +#### Note: Certificate Chains +If you have multiple certificates to load into OpenShift, you must pass each with its own identifier. ```bash -ca0.crt: -\> a single ca certificate -ca1.crt: -\> another ca certificate +ca0.crt: → a single CA certificate +ca1.crt: → another CA certificate ... -ca5.crt -\> last ca certificate +ca5.crt → last CA certificate ``` - See the [Next Steps](#next-steps) below to continue your work with Entando. ## Next Steps From c9a76a1f817c9471d43cd48541c94336d982be0b Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Wed, 3 Aug 2022 16:50:41 -0500 Subject: [PATCH 29/34] ENDOC-535-ssl-note tiny edit --- .../tutorials/getting-started/openshift-install-by-operator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md b/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md index c4b7a80a84..fcedfdf6c0 100644 --- a/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md +++ b/vuepress/docs/v7.0/tutorials/getting-started/openshift-install-by-operator.md @@ -116,7 +116,7 @@ type: kubernetes.io/tls Now create the `entando-ca-cert-secret` Secret, similar to what was done in Scenario 3, but this time using the self-signed certificate. -4. Go to `Workloads` → `Secrets` → `Create` and select `Key/value secret`\ +4. Go to `Workloads` → `Secrets` → `Create` and select `Key/value secret` For multiple certificates, see note below on [Certificate Chains](#note-certificate-chains). 5. Set the `Secret Name`, e.g. `entando-ca-cert-secret` From 5db81daf17ed615bdaf5605177e0d879224e9873 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Thu, 4 Aug 2022 10:49:01 -0500 Subject: [PATCH 30/34] ENDOC-522 final check edits --- vuepress/docs/.vuepress/next.js | 10 +++++----- vuepress/docs/next/docs/getting-started/ent-api.md | 2 +- vuepress/docs/next/docs/getting-started/ent-diag.md | 2 +- vuepress/docs/next/docs/getting-started/ent-profile.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/vuepress/docs/.vuepress/next.js b/vuepress/docs/.vuepress/next.js index 6198e4f423..88d2f6f545 100644 --- a/vuepress/docs/.vuepress/next.js +++ b/vuepress/docs/.vuepress/next.js @@ -28,23 +28,23 @@ module.exports = { path: path + 'getting-started/entando-cli.md', }, { - title: 'ent Bundle Management', + title: 'Bundle Management', path: path + 'getting-started/ent-bundle.md', }, { - title: 'ent API Management', + title: 'API Management', path: path + 'getting-started/ent-api.md', }, { - title: 'ent Services Management', + title: 'Services Management', path: path + 'getting-started/ent-svc.md', }, { - title: 'ent Profile Management', + title: 'Profile Management', path: path + 'getting-started/ent-profile.md', }, { - title: 'ent Diagnostics and Troubleshooting', + title: 'Diagnostics and Troubleshooting', path: path + 'getting-started/ent-diag.md', } ] diff --git a/vuepress/docs/next/docs/getting-started/ent-api.md b/vuepress/docs/next/docs/getting-started/ent-api.md index 722a322b27..c45967fafe 100644 --- a/vuepress/docs/next/docs/getting-started/ent-api.md +++ b/vuepress/docs/next/docs/getting-started/ent-api.md @@ -3,7 +3,7 @@ sidebarDepth: 1 --- -# Overview +# API Management An API claim informs the Entando Platform that a micro frontend (MFE) intends to use the API of a microservice (MS). This request can be sent within a single bundle or across bundles. The abstraction of an API claim eliminates the need to define and manage API endpoints, both in local development and within a running instance. diff --git a/vuepress/docs/next/docs/getting-started/ent-diag.md b/vuepress/docs/next/docs/getting-started/ent-diag.md index 7ee646f899..b47d186ef7 100644 --- a/vuepress/docs/next/docs/getting-started/ent-diag.md +++ b/vuepress/docs/next/docs/getting-started/ent-diag.md @@ -4,7 +4,7 @@ sidebarDepth: 1 # Diagnostics and Troubleshooting -Diagnostic information is critical to analysis and troubleshooting, and the Entando CLI (ent) is a useful tool for debugging issues with an Entando instance. The [Getting Started](../../docs/getting-started/README.md) guide includes steps to install ent in a Multipass VM. The following commands can be run from this VM for insight into an Entando Application. +Diagnostic information is critical to analysis and troubleshooting, and the Entando CLI (ent) is a useful tool for debugging issues with an Entando instance. | Command | Description | :- | :- diff --git a/vuepress/docs/next/docs/getting-started/ent-profile.md b/vuepress/docs/next/docs/getting-started/ent-profile.md index 446dd06bc1..b3718f0853 100644 --- a/vuepress/docs/next/docs/getting-started/ent-profile.md +++ b/vuepress/docs/next/docs/getting-started/ent-profile.md @@ -3,7 +3,7 @@ sidebarDepth: 1 --- -# Overview +# Profile and Configuration Management The [Entando CLI](entando-cli.md) can define a collection of configuration variables to fully describe an Entando instance. One or more profiles can be created to store configuration settings for a particular instance. A profile with this information is automatically generated for a quickstart application. From a6044383c1e9efd62bee9cd1e4182db4508733df Mon Sep 17 00:00:00 2001 From: Nathan Shaw Date: Thu, 4 Aug 2022 15:11:06 -0400 Subject: [PATCH 31/34] ENDOC-537 Add shortcuts --- vuepress/README.md | 2 +- vuepress/docs/cli.md | 2 ++ vuepress/docs/hub.md | 2 ++ 3 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 vuepress/docs/cli.md create mode 100644 vuepress/docs/hub.md diff --git a/vuepress/README.md b/vuepress/README.md index becd9b7d71..178f55625a 100644 --- a/vuepress/README.md +++ b/vuepress/README.md @@ -77,7 +77,7 @@ We have a simple versioning system in place currently. Creating a new version in 1. Add the new version to `extraWatchFiles` 1. Add sidebars for the new version under `themeConfig.sidebar` 1. Add the new version to `navLinks.js` -1. Modify Getting Started guide (top-level page, docs/getting-started and quick reference) to update references to jhipster, etc. to point to the appropriate build or package versions. +1. Modify Getting Started guide (top-level pages like cli.md and hub.md, docs/getting-started and quick reference) to update references to jhipster, etc. to point to the appropriate build or package versions. 1. Search for `/next` and `/vX.(Y-1)` references in the new vX.Y docs. If common practices have been followed, all docs should be using relative references so this should result in no additional changes. Please note that custom-resources.md has multiple absolute and relative links that should be checked with any version updates. 1. Run `yarn docs:check-md` to check for broken links. 1. Publish to the staging site and run the deadlink checker on it diff --git a/vuepress/docs/cli.md b/vuepress/docs/cli.md new file mode 100644 index 0000000000..2a405d53f0 --- /dev/null +++ b/vuepress/docs/cli.md @@ -0,0 +1,2 @@ +Redirecting to the latest Entando CLI information... + \ No newline at end of file diff --git a/vuepress/docs/hub.md b/vuepress/docs/hub.md new file mode 100644 index 0000000000..1c0ccce2ab --- /dev/null +++ b/vuepress/docs/hub.md @@ -0,0 +1,2 @@ +Redirecting to the latest Entando Hub information... + \ No newline at end of file From 4987c5781f8e30a9bcac2f340c633e444ba99f45 Mon Sep 17 00:00:00 2001 From: jyunmitch Date: Fri, 12 Aug 2022 16:17:29 -0500 Subject: [PATCH 32/34] 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 33/34] 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 34/34] 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