Merge branch 'main' into ENDOC-533

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

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: 'Bundle Management',
+                            path: path + 'getting-started/ent-bundle.md',
+                            },
+                            {
+                                title: 'API Management',
+                            path: path + 'getting-started/ent-api.md',
+                            },
+                            {
+                                title: 'Services Management',
+                            path: path + 'getting-started/ent-svc.md',
+                            },
+                            {
+                                title: 'Profile Management',
+                            path: path + 'getting-started/ent-profile.md',
+                            },
+                            {
+                                title: 'Diagnostics and Troubleshooting',
+                            path: path + 'getting-started/ent-diag.md',
+                            }
+                        ]
+
+                    }
+
                 ]
             },
             {
@@ -125,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'

vuepress/docs/cli.md

@@ -0,0 +1,2 @@
+Redirecting to the latest Entando CLI information...
+<EntandoRedirect to="./v7.0/docs/reference/entando-cli.html" />

vuepress/docs/hub.md

@@ -0,0 +1,2 @@
+Redirecting to the latest Entando Hub information...
+<EntandoRedirect to="./v7.0/tutorials/solution/entando-hub.html" />

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
 

vuepress/docs/next/docs/getting-started/ent-api.md

@@ -0,0 +1,89 @@
+---
+sidebarDepth: 1
+---
+
+
+# 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.
+
+## Internal vs. External API Claim
+
+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:
+
+**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. 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
+| :- | :-
+| `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:
+   - `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 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
+
+- Executing `api add-ext` without flags:
+   - Returns the current instance
+   - Displays the instance's available services for interactive selection
+
+## 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. `<my-mfe config="{ ... }" />`.
+
+**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 that 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.
+
+The commands that add and remove API claims update `mfe-config.json` automatically.

vuepress/docs/next/docs/getting-started/ent-bundle.md

@@ -0,0 +1,168 @@
+---
+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 steps required to create an Entando Bundle.
+
+1. [Initialization](#initialization)
+2. [Build](#build)
+3. [Run](#run)
+4. [Package](#package)
+5. [Publish](#publish)
+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
+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. 
+
+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 
+| Commands | Subcommands|  Description
+|:-|:-|:----------------------------------
+|`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 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)
+|`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 empty 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 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 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 micro frontends|
+
+#### Command Details
+`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
+|:--|:--
+|`ent bundle run [component-name]` | Locally run your single component
+|`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 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: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 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.
+
+## Publish
+| Command| Descriptions
+|:--|:--
+|`ent bundle publish`| Publish your Docker images to a Docker registry (default)
+|`ent bundle publish --org [organization]`|Publish Docker images to the Docker registry, with a specified organization |
+|`ent bundle publish --registry [registry]`| Publish the Docker images to your Docker registry|
+
+## ECR Commands
+Entando provides a series of `ent ecr` commands for managing bundle interactions with [the Entando Component Repository](../../docs/compose/ecr-overview.md) (ECR).
+
+| Command| Descriptions
+|:--|:--
+|`ent ecr deploy`| Generate the custom resource (CR) and deploy it to the current profile |
+|`ent ecr gen-secret`| Generate and display a plugin Secret skeleton|
+|`ent ecr 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 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|
+|`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 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.
+
+## 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 deploy`| Deploy the bundle into the ECR|
+|`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-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
+|`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-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.
+
+     * 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
+            ```
+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.