# Entando CLI

# Overview

The Entando Command Line Interface (CLI) provides a set of commands that accelerate the developer experience by assisting the developer with common tasks such as quickly installing a new copy of Entando, generating an Entando project via JHipster, deploying an Entando Bundle, etc.

# Installation

# Prerequisites

The basic requirements for the CLI vary depending on the category of developer tasks. The Entando CLI is able to install secondary dependencies using the ent check-env command as described here.

Category	Prerequisite
Basic Development	git or git for windows (opens new window)
	nvm or nvm for windows (opens new window)
Install Entando in a local VM	multipass (opens new window)
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. This could be a local cluster (created via the CLI or manually) or a shared remote cluster.

TIP

If you follow the automated option in Getting Started, then the CLI will be installed for you 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.

curl -L https://get.entando.org/cli | bash

# Check Environment

Use the check-env command to prepare your environment for development. This will verify the presence of additional dependencies (such as git, curl, java, JHipster, etc.) as well as the appropriate versions for your specific Entando instance. In most cases check-env will automatically install those dependencies and will prompt the developer for guidance or approval as needed.

ent check-env develop

# Update the CLI

The CLI can be updated to the latest version (corresponding to your Entando version) using the following command. You should run ent check-env develop after updating the CLI in case any dependency versions have changed.

bash <(curl -L "https://get.entando.org/cli") --update

# Available Commands

Use ent help to review the list of available commands.

~~~~~~~~~~~~~~~~~~~
 Entando CLI
~~~~~~~~~~~~~~~~~~~

> Available commands:
  - app                  => Helps managing an EntandoApp
  - 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 some diagnostic and collects the related info in a tgz file
  - ecr                  => Helps managing an the Entando ECR
  - ent                  => Helps managing an the local ents
  - help                 => Helps in having help
  - host                 => Helps 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. This is mostly for internal use
  - pod                  => Displays information related to a set of pods
  - prj                  => Helps managing Entando bundle projects
  - profile              => Helps managing an EntandoApp
  - quickstart           => Helps locally installing entando instances
  - run-tests            => Run the internal tests

> Further info about entando:
  - https://www.entando.com/
  - https://developer.entando.com/

> ⚠ RECOMMENDED FIRST STEP ⚠ :
  - Check the dependencies (ent check-env --help)

Check the help text (--help) for any command to see its specific options, e.g. ent check-env --help.

# Project Management

These are common sequences for an Entando project.

# Project Setup

Setup a project directory

mkdir testProject && cd testProject

Generate the project skeleton using the JHipster-based Entando Blueprint.

ent jhipster --blueprints entando

Generate an entity and MFEs.

ent jhipster entity Conference

Build the new project. Using the ent-prj wrapper saves having to build each part of the project individually. The first run can be slower due to node downloads for any MFEs.

ent prj build

See this tutorial for more details.

# Prepare and Publish a Bundle

Use the publication system (pbs) to assemble your Entando project into a bundle that can be loaded into Kubernetes. You'll need your github credentials, a github repository to hold your bundle artifacts, and a Docker Hub account or organization.

Initialize the bundle directory

ent prj pbs-init

Publish the build artifacts to github and Docker Hub

ent prj pbs-publish

Deploy the bundle into the Entando Component Repository.

ent prj deploy

See this tutorial for more details.

# Install the bundle into an application

The ent CLI allows you to install a bundle without the need to access the Entando App Builder. Note: To install a given bundle, you need to be sure it has been deployed first.

In your project folder run the following command

ent prj install

If you already installed the bundle, you can use --conflict-strategy to adopt a strategy for existing components (CREATE, SKIP, OVERRIDE)

ent prj install --conflict-strategy=OVERRIDE

# Run a Project locally

Startup Keycloak. This uses docker-compose under the hood.

ent prj ext-keycloak start

Startup the backend microservices

ent prj be-test-run

Startup one or more of the frontend widgets, each from its own shell.

ent prj fe-test-run

See this tutorial for more details.

Alternatively, you can perform a completely clean install of the CLI by removing your ~/.entando directory and then reinstalling the CLI per the instructions above. This will also remove the private copies of JHipster, Entando Blueprint, etc.

rm -rf ~/.entando.

# Bundle Commands

Use the ent bundler command to prepare a bundle for publication or extract a bundle from an application.

Prepare a bundle custom resource from a Git repository. The project command (ent prj generate-cr) provides a wrapped version of this command. See the help for options including the bundle name, description, repository, etc. The output of this command is a yaml file which can be piped to a file or directly to ent kubectl for application to Kubernetes.

  ent bundler from-git

See this tutorial for an example using this command.

Point the bundler to an existing Entando application and extract its components (pages, content, etc.) and static assets into a custom bundle. You can use this bundle to migrate Entando components from one environment to another (e.g. Dev to QA), to provide a template for building a new Entando application, or as the skeleton of an Entando solution. The bundler provides an interactive mode which allows you to identify the components to be exported from the application. The output of this command is the same bundle folder structure created by an Entando project including a top-level descriptor file.

  ent bundler from-env

You will need to provide an env.json file in the same directory where the bundler is run. This is used to configure the application URLs and client credentials.

{
   "coreBaseApi": "http://<YOUR-DOMAIN-OR-IP>/entando-de-app",
   "k8ssvcApi": "http://<YOUR-DOMAIN-OR-IP>/k8s",
   "clientId": "<YOUR-CLIENT-ID>",
   "clientSecret": "<YOUR-CLIENT-SECRET>"
}

See this tutorial for more instructions on exporting a bundle including how to setup your env.json.

# Profile Management

ent profile is essentially a command to manage and switch between different configurations. It's commonly used to switch between different Entando applications, even if they are on different clusters. In order to do this, ent profile can be instructed to use kubernetes contextes, kubeconfig files, custom commands or a combination of them. (checkout ent profile first-use-readme).

Create a new profile. You need to give the profile name, the Entando application name and the namespace.

ent pro new [profileName] [EntandoAppName] [namespace]

Link the current profile to a kubernetes context by the name

ent pro link [contextName]

Activate a profile by its name

ent pro use [profileName]

Please note you can use a profile only for the current shell by using this command instead.

source ent pro use [profileName]

List the available profiles

ent pro list

Delete a profile

ent pro delete [profileName]

# Configuration management

ent config is a key-value archive of configurations related to the current profile. It can serve several purposes, but these are a few "good to know" keys and commands.

# Commands

Print the current config archive

ent config --print

Interactively edits the config archive

ent config --edit

Get a given config key value

ent config --get {key}

Set a given config key to a given value

ent config --set {key} {value}

Delete the given config key

ent config --set {key}

# Good to know keys

Key	Definition
ENTANDO_NAMESPACE	stores the fallback namespace used by explicit or implicit runs of "ent kubectl"
ENTANDO_APPNAME	stores the EntandoApp name related to the current profile location profile
DESIGNATED_JAVA_HOME	stores the path of the java version internally used by ent

# Diagnostic Commands

The following commands can be useful to more quickly understand what is happening with an Entando Application. If you followed the Getting Started steps to setup Entando then the CLI was automatically installed in the Multipass VM and you can run these commands from there.

ent app-info display basic information about Kubernetes and the Entando resources (e.g. namespace, pods, ingresses)

ent app-info

ent pod-info display the kubectl describe and kubectl logs for each of the major Entando pods in a given namespace.

ent pod-info

ent diag list the current pods in a given Entando namespace and prepare a diagnostic tar.gz containing kubectl describe and kubectl logs for each of the major Entando pods. This can be highly useful when working with Entando Support.

ent diag

Output:

ubuntu@entando:~$ ent diag
Please provide the namespace (entando):
## DNS rebinding protection TEST
## LOCAL INFO
## K8S INFO
> POD: quickstart-kc-deployer-pbyjdp1dom
>       CONTAINER: deployer
> POD: quickstart-eci-deployer-smectg3hxy
>       CONTAINER: deployer
> POD: quickstart-deployer-9ul8cyjtiq
>       CONTAINER: deployer
> POD: quickstart-composite-app-deployer-nlz9lxc6do
>       CONTAINER: deployer
> POD: quickstart-eci-k8s-svc-deployment-79c4894767-5p85d
>       CONTAINER: k8s-svc-container
> POD: quickstart-kc-server-deployment-85987fc84c-flrlw
>       CONTAINER: server-container
> POD: quickstart-operator-7bfd7fc8cd-gd774
>       CONTAINER: operator
> POD: quickstart-server-deployment-f69f84798-g6lx5
>       CONTAINER: server-container
>       CONTAINER: de-container
>       CONTAINER: appbuilder-container
> 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"

# Reference

Source repository: https://github.com/entando/entando-cli/tree/develop (opens new window)

← Entando Identity Management System Deployment Structure →