From 765ca3a6d5afdf7169b831adbb0403f4b4cf79a2 Mon Sep 17 00:00:00 2001 From: Jinah Yun-Mitchell Date: Thu, 12 Sep 2024 15:56:02 -0500 Subject: [PATCH] ENDOC-809 general updates compose & consume --- .../next/docs/compose/preinstalled-widgets.md | 10 ++--- .../docs/next/docs/compose/welcome-wizard.md | 14 +++++-- .../docs/next/docs/consume/accessibility.md | 31 ++++++-------- .../docs/next/docs/consume/entando-apis.md | 15 +++---- .../docs/consume/high-avail-application.md | 13 +++--- .../next/docs/consume/identity-management.md | 28 +++++++------ .../docs/next/docs/consume/multitenancy.md | 17 ++++---- .../docs/next/docs/consume/operator-intro.md | 40 ++++++++++--------- .../v7.3/docs/compose/preinstalled-widgets.md | 10 ++--- .../docs/v7.3/docs/compose/welcome-wizard.md | 14 +++++-- .../docs/v7.3/docs/consume/accessibility.md | 31 ++++++-------- .../docs/v7.3/docs/consume/entando-apis.md | 15 +++---- .../docs/consume/high-avail-application.md | 13 +++--- .../v7.3/docs/consume/identity-management.md | 28 +++++++------ .../docs/v7.3/docs/consume/multitenancy.md | 17 ++++---- .../docs/v7.3/docs/consume/operator-intro.md | 40 ++++++++++--------- 16 files changed, 176 insertions(+), 160 deletions(-) diff --git a/vuepress/docs/next/docs/compose/preinstalled-widgets.md b/vuepress/docs/next/docs/compose/preinstalled-widgets.md index 852ec0abf2..ab701dc7ac 100644 --- a/vuepress/docs/next/docs/compose/preinstalled-widgets.md +++ b/vuepress/docs/next/docs/compose/preinstalled-widgets.md @@ -7,7 +7,7 @@ sidebarDepth: 2 The Entando Platform includes a number of useful components to accelerate application development. These consist of widgets, page templates, content templates, and content types. -This page introduces the widgets that are available out of the box with an Entando 7 installation. These widgets are categorized by type, where each type implements CMS, navigation, page, SEO or system functionality. +This page introduces the widgets that are available out of the box with Entando. The widgets are categorized by type, each with its own CMS, navigation, pages, SEO and/or system functionality. ## Widget Attributes @@ -18,12 +18,12 @@ All widgets are required to have the following attributes. These are mandatory r - `Group`: A group for which the user has "create" permissions - `Icon`: A graphic that visually represents the widget via an uploaded icon (SVG file) or one chosen from the icon library - `Custom UI`: HTML code that constructs the visual layout of the widget -- `Config UI`: A JSON structure that informs the widget's configuration. It requires two properties: +- `Config UI`: A JSON structure that defines the widget's configuration. It requires two properties: - `customElement`: The custom element name of the widget config component - `resources`: An array listing the source location of the custom element files for the widget configuration ## Widget Descriptions -The following table lists the notable preinstalled widgets of an Entando instance. They can be accessed from the left menu of the App Builder by selecting `Components` → `MFE & Widgets`. +The following table lists the notable preinstalled widgets of an Entando instance. They are accessible from the left menu of the App Builder by selecting `Components` → `MFE & Widgets`. | Name | Type | Description | @@ -32,12 +32,12 @@ The following table lists the notable preinstalled widgets of an Entando instanc | Content List | CMS | A widget that renders a list of contents, each one displaying information from a template | | Content Search Query | CMS | A widget that publishes a list of contents based on different settings | | Content SEO Meta-description | SEO | A component listing the SEO parameters specified when pages are created or modified | -| Internal Servlet | System | A legacy implementation to create server-side widgets using Struts 2. Available for backwards compatibility with older projects. | +| Internal Servlet | System | A legacy implementation to create server-side widgets using Struts 2. Available for backwards compatibility. | | Legacy Login Form | System | A non-Keycloak form component for logging in | | Legacy Navigation Menu | Navigation | An interface that is configurable via expression list parameters. A user with admin privileges can easily change its layout. | | Login | System | The Keycloak-powered login/logout component for the web app | | Logo | Page | The default Entando logo. It can be used in other projects by changing its fragment reference. | -| Navigation Menu | Navigation | An OOTB widget configurable via expression list parameters | +| Navigation Menu | Navigation | A widget configurable via expression list parameters | | Search Form | CMS | A basic search form | | Search Results | CMS | A component that shows the results of the query entered into the Search Form | diff --git a/vuepress/docs/next/docs/compose/welcome-wizard.md b/vuepress/docs/next/docs/compose/welcome-wizard.md index 5429c568d1..017cb09d6e 100644 --- a/vuepress/docs/next/docs/compose/welcome-wizard.md +++ b/vuepress/docs/next/docs/compose/welcome-wizard.md @@ -1,12 +1,18 @@ +--- +sidebarDepth: 2 +--- + # Welcome Wizard -The Welcome Wizard is displayed when you first log in to the Application Builder. You can also start it later by going to the top navigation bar in the Application Builder, click on the information icon, and click `Begin Welcome Wizard`. You can disable it from the wizard popup by selecting `Don't show next time` and then `Close`, or by going to `My Profile → Preferences` and setting the `Welcome Wizard` preference to `Off`. +The Welcome Wizard is activated and displayed when you first log in to the App Builder. It provides a guided tour of how to begin creating your application. + +If you need to review it at any time, click on the information icon in the top navigation bar, then select `Start Welcome Wizard`. You can slso disable it by checking `Don't show next time` in the popup window, or by going to `My Profile` → `Preferences` and setting the `Welcome Wizard` preference to `Off`. -![./img/welcome-wizard.png](./img/welcome-wizard.png) +![Screenshot-Welcome Wizard popup to create first application](./img/welcome-wizard.png) -The Wizard will guide you through the key steps in designing and publishing a page in your application: +The Wizard will guide you through the key steps in designing and publishing a page for your application. It looks something like this: 1. Create a Page by setting its title, code, location, group, and template. -2. Design the Page by placing a set of pre-configured widgets on the page. +2. Design the Page by placing a set of pre-configured components on the page. 3. Preview the Page 4. Publish the Page diff --git a/vuepress/docs/next/docs/consume/accessibility.md b/vuepress/docs/next/docs/consume/accessibility.md index 45f0e4ae60..89249d10fc 100644 --- a/vuepress/docs/next/docs/consume/accessibility.md +++ b/vuepress/docs/next/docs/consume/accessibility.md @@ -1,9 +1,12 @@ +--- +sidebarDepth: 2 +--- + # Web Accessibility in Entando -> The power of the Web is in its universality. -> Access by everyone regardless of disability is an essential aspect. +**The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect.** -`- Tim Berners-Lee, W3C Director and inventor of the World Wide Web` +-- Tim Berners-Lee, W3C Director and inventor of the World Wide Web Web accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities can use them. Accessibility is essential for developers and organizations that want to create high-quality @@ -12,42 +15,34 @@ See [w3.org](https://www.w3.org/WAI/fundamentals/accessibility-intro/) for an in ## Requirements and Standards -Many projects and programs will have specific requirements in the area of accessibility, particularly for applications +Many projects and programs have specific requirements in terms of accessibility, particularly for applications or sites with a broad reach or specific governance considerations. Entando's approach to accessibility is to provide the tools and techniques that allow a development team to meet their own specific accessibility requirements. -Development teams will need someone to become familiar with the relevant accessibility standards and help make design -decisions on how they will be applied to a specific project. Those standards vary by region so please check the +Development teams need someone to become familiar with the relevant accessibility standards to help make design +decisions on how they can be applied to specific projects. These standards may vary by region so please check the legislation in your area or consult an accessibility specialist. Useful resources include: * [W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/design-develop/) * [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) * USA: [Section 508 of the Rehabilitation Act](https://www.section508.gov/manage/laws-and-policies) -At the end of the day it's up to a development team to make sure their implementation is compliant with a specific -guideline or standard. Typically a team will make use of Entando Page Templates, Content Templates, and custom micro -frontends in order to accomplish this goal. +At the end of the day, it's up to the development team to make sure their implementation is compliant with specific guidelines or standards. Typically a team will make use of Entando Page Templates, Content Templates, and custom micro frontends in order to accomplish this goal. ## Tools -Accessibility requirements are ideally known at the start of a project so the design language and tools can be adopted -early in the project. Using them consistently will ease implementation of the accessibility elements needed to meet the -desired compliance level. Retrofitting a project for accessibility can be done but is typically more involved. Example +Accessibility requirements are ideally known at the start of a project so the design language and tools can be adopted early in the project. Using them consistently will ease implementation of the accessibility elements needed to meet the desired compliance level. Retrofitting a project for inclusive design can be done but is typically more involved. Example design systems used by Entando clients include: -* [Material-UI](https://material-ui.com/) - a React framework used to build a custom design system and/or one based on - Material Design. +* [Material-UI](https://material-ui.com/) - a React framework used to build a custom design system and/or one based on Material Design. * [Carbon Design System](https://www.carbondesignsystem.com/) - IBM's open source design system * [Bootstrap Italia](https://github.com/italia/bootstrap-italia) - a Bootstrap 4-based frontend theme that implements the Italian Design Guidelines for public websites. -Assessing web accessibility is important throughout the life of a project. There are many tools available in this area. A -useful list can be found [on the W3C site](https://www.w3.org/WAI/ER/tools/) with filters by guideline, region, -language, etc. Entando clients have made good use of the following: +Evaluating web accessibility is important throughout the life of a project. There are many tools available in this area. A useful list can be found [on the W3C site](https://www.w3.org/WAI/ER/tools/) with filters by guideline, region, language, etc. The following resources have been found useful by Entando clients: * [a11y.css](https://chrome.google.com/webstore/detail/a11ycss/iolfinldndiiobhednboghogkiopppid) * [Access Assistant](https://chrome.google.com/webstore/detail/access-assistant/ojiighldhdmahfdnhfdebnpmlbiemdfm) -* [Continuum Explorer Pro](https://chrome.google.com/webstore/detail/continuum-explorer-pro/pgkgokkkoamjdmbnegbedepbhbgecplj) * [Wave (web accessibility evaluation tool)](https://wave.webaim.org/) diff --git a/vuepress/docs/next/docs/consume/entando-apis.md b/vuepress/docs/next/docs/consume/entando-apis.md index e53dc841a2..5d51a62b3c 100644 --- a/vuepress/docs/next/docs/consume/entando-apis.md +++ b/vuepress/docs/next/docs/consume/entando-apis.md @@ -4,7 +4,7 @@ sidebarDepth: 2 # Accessing Entando APIs -Entando includes the Swagger UI for API access in a quickstart environment. This document presents an overview and instructions on how to enable and access the Swagger UI. +Entando includes the Swagger UI for API access in a quickstart environment. This document presents an overview, and instructions on how to enable and utilize the interface. ## APIs Overview The Entando App Engine uses REST APIs to enact all the functionality inside the App Builder. For example, APIs are used to add widgets to a page or create components like pages and page templates. APIs can also be used to support automation, testing, and integration with external systems. @@ -19,13 +19,14 @@ All of the model classes returned by the Entando App Engine are annotated with d ## Enable the Swagger UI -The Swagger UI can be enabled or disabled in a running Entando instance by modifying the `SPRING_PROFILES_ACTIVE` environment variable for the `entando-de-app` container. +The Swagger UI can be enabled or disabled in a running Entando instance by modifying the environment variable `SPRING_PROFILES_ACTIVE` in the `entando-de-app` container. 1. (Optional) Scale the deployment `spec.replicas` to 0. >This is necessary if you're using an in-memory database as in the default quickstart configuration. This will prevent database errors on immediate restarts when the deployment is changed. -2. Edit the `entando-de-app` deployment. If you have different names for deployment and namespace, adjust the command below accordingly. +2. Edit the `entando-de-app` deployment. If you have different names for namespace and deployment, adjust the command accordingingly. + >Use the [ent CLI](../getting-started/entando-cli.md) to send commands to Kubernetes from the host machine. ``` @@ -46,16 +47,16 @@ kubectl -n entando edit deployment/quickstart-deployment Repeat the steps above, but in step 4, remove `swagger` from the value list. -## Find Your Client Secret +## Retrieve Your Client Secret You'll need your client credentials to execute Entando APIs. -1. Log in into your Keycloak Administration Console at `http://[YOUR-HOST-NAME]/auth`. To find the Keycloak admin credentials, see the [Entando Identity Management System](./identity-management.md) page. +1. Log in to your Keycloak Administration Console at `http://[YOUR-HOST-NAME]/auth`. To find the Keycloak admin credentials, see the [Entando Identity Management System](./identity-management.md) page. 2. From the left navigation panel, go to `Clients` 3. Select the desired client (e.g. in a quickstart environment, this is `quickstart`) -4. Click on the `Credentials` tab to retrieve the Secret. Save the `Client Id` and `Secret` for the steps below. +4. Click on the `Credentials` tab to find the Secret. Save the `Client Id` and `Secret` for the steps below. ## Access the APIs on Swagger 1. To see the APIs, go to: @@ -65,7 +66,7 @@ http://[YOUR-HOST-NAME]/entando-de-app/api/swagger-ui.html 2. Click on the Authorize button in the upper right corner. -3. Enter the client ID and Secret from above. Click Authorize. +3. Enter the `Client ID` and `Secret` from above. Click `Authorize`. 4. You will be prompted to log in to your Keycloak instance as an Entando admin user if you have not already done so. The default credentials are admin/adminadmin. diff --git a/vuepress/docs/next/docs/consume/high-avail-application.md b/vuepress/docs/next/docs/consume/high-avail-application.md index 9112fe71bf..c4f931714e 100644 --- a/vuepress/docs/next/docs/consume/high-avail-application.md +++ b/vuepress/docs/next/docs/consume/high-avail-application.md @@ -1,3 +1,6 @@ +--- +sidebarDepth: 2 +--- # High Availability in an Entando Application ## App Engine Clustering and High Availability @@ -6,7 +9,7 @@ The Entando App Engine can be deployed as a clustered set of instances using the This document examines the issues to consider when creating highly availailable clusters of the Entando App Engine. -Microservices clustering that adds functionality to an Entando Application is different from clustering used by the Entando App Engine. Microservices rely on a custom clustering configuration and setup based on implementation and selections made during their creation. Refer to documentation addressing [clustered microservices and caching implementation](../../tutorials/consume/high-availability.md) for configuration and deployment details. +Microservices clustering that adds functionality to an Entando Application is different from clustering used by the Entando App Engine. Microservices rely on a custom clustering configuration and setup based on implementation, and selections made during their creation. Refer to the documentation addressing [clustered microservices and caching implementation](../../tutorials/consume/high-availability.md) for more details. ::: tip @@ -31,18 +34,18 @@ The following objects are cached in the base implementation of the Entando App E - Languages - Labels (i18n) - User profiles -- API Catalog (legacy API metadata separate from swagger) +- API Catalog (legacy API metadata separate from Swagger) - Data models and data types (deprecated) ## Redis Implementation -An Entando Application can be configured to utilize an external [Redis](https://redis.io/) cache. In a Redis implementation of an Entando Application, the cache is deployed independently of the Entando App Engine and the App Engine is configured to connect to the deployed instance. +An Entando Application can be configured to utilize an external [Redis](https://redis.io/) cache. In a Redis implementation of an Entando Application, the cache is deployed independently of the Entando App Engine and the Engine is configured to connect to the deployed instance. -![Redis Caching](./img/redis-caching.png) +![Entando Architecture with Redis Caching](./img/redis-caching.png) The Redis cache is not deployed by the Entando Operator and must be managed by a DevOps team member or Kubernetes cluster administrator. -Check out the [High Availability on Entando tutorial](../../tutorials/consume/high-availability.md#clustering) for more information and step-by-step instructions to use a Redis cache in an Entando Application. +Check out the [High Availability on Entando tutorial](../../tutorials/consume/high-availability.md#clustering) for more information and step-by-step instructions on using a Redis cache. ## Performance diff --git a/vuepress/docs/next/docs/consume/identity-management.md b/vuepress/docs/next/docs/consume/identity-management.md index 23d9753311..a7787bb633 100644 --- a/vuepress/docs/next/docs/consume/identity-management.md +++ b/vuepress/docs/next/docs/consume/identity-management.md @@ -1,6 +1,9 @@ +--- +sidebarDepth: 2 +--- # Entando Identity Management System -The Entando Identity Management System is based on open source Keycloak. Entando Applications rely on a Keycloak instance that is either [externally installed](../../tutorials/consume/external-id-management.md) or specific to an application. The architecture and requirements to customize your Keycloak instance are described below. +The Entando Identity Management System is based on the open source Keycloak identity and access management system. Entando Applications rely on a Keycloak instance that is either [externally installed](../../tutorials/consume/external-id-management.md) or specific to an application. The architecture and requirements to customize your Keycloak instance are described below. ## Logging into your Keycloak Instance @@ -20,33 +23,34 @@ kubectl get secrets -n entando ## Authentication All authentication is powered by Keycloak on Entando. This ensures that a micro frontend can call a microservice with a token available to the client. -![Init Containers Screenshot](./img/keycloak-arch-high-level.png) +![Entando cluster & Keycloak architecture diagram with JWT tokens](./img/keycloak-arch-high-level.png) -Entando implements Keycloak as a central point of authentication to provide a single, unified view of identity. This architecture increases portability. Keycloak acts as an abstraction layer to the underlying Identity Provider (IDP), allowing Entando to integrate into other IDPs without modifying the source. +Entando implements Keycloak as a central point of authentication to provide a single unified view of identity. This infrastructure increases portability. Keycloak acts as an abstraction layer to the underlying Identity Provider (IDP), allowing Entando to integrate into other IDPs without modifying the source. ## Authorization ### Role Assignment for Plugins/Microservices Keycloak authorizes microservices using clients and roles. Authorizations are stored in a JSON Web Token and available to services when invoked. -Below are the steps to grant a user one or more roles for a specific client. This controls permissions when configuring the microservice. Note: when a microservice is installed in Entando, a corresponding client (and set of roles) is created per its plugin definition. +Below are the steps to grant a user one or more roles for a specific client. This controls permissions when configuring the microservice. Note, when a microservice is installed in Entando, a corresponding client (and set of roles) is created within its plugin definition. -1. [Login to Keycloak](#logging-into-your-keycloak-instance), which for non-external Keycloak instances is [the base URL of your running Entando application](../getting-started/README.md#configure-access-to-your-cluster) followed by `/auth/`, e.g. http://YOUR-HOST-NAME/auth. In a standard Entando installation, the base URL can be verified with `kubectl get ingress/default-sso-in-namespace-ingress`. -2. Select `Users` from the menu on the left +1. [Login to Keycloak](#logging-into-your-keycloak-instance) +>For non-external Keycloak instances, it is [the base URL of your running Entando application](../getting-started/README.md#configure-access-to-your-cluster) followed by `/auth/`, e.g. http://YOUR-HOST-NAME/auth. In a standard Entando installation, the base URL can be verified with `kubectl get ingress/default-sso-in-namespace-ingress`. +2. Select `Users` from the left menu 3. Use the search box to find the appropriate user, e.g. "admin" 4. Click on the user ID -![find-admin.png](./img/find-admin.png) +![Screenshot-AppBuilder Users Lookup for admin](./img/find-admin.png) -5. Click on the `Role Mappings` tab +5. Click the `Role Mappings` tab 6. Use the `Client Roles` drop-down menu to specify the microservice client 7. Select from the client's `Available Roles` -![find-roles.png](./img/find-roles.png) +![Screenshot-Client Roles Dropdown of Available Roles](./img/find-roles.png) 8. Use the `Add Selected` button to move the desired roles to `Assigned Roles`. These will subsequently appear under `Effective Roles`. -![assign-roles.png](./img/assign-roles.png) +![Screenshot-Roles added to Effective Roles](./img/assign-roles.png) ### Core When a user is authenticated to the `entando-core` via Keycloak, a copy of that user is added to the `entando-core` user management database to enable WCMS functionality. Within the App Builder, WCMS roles and groups can be assigned to a user for access to App Builder functions or `portal-ui` content in the runtime application. @@ -60,8 +64,8 @@ Keycloak allows Entando to provide social login as an out-of-the-box capability. ## One Time Passwords -Keycloak enables One Time Passwords (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/18.0/server_admin/index.html#one-time-password-otp-policies) to configure and enable OTP in your application. +Keycloak enables One Time Password (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/18.0/server_admin/index.html#one-time-password-otp-policies) to configure and enable it. ## Themes, Look and Feel -Developers can customize the look and feel of the login page, as well as the identity management system that ships with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/18.0/server_development/#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). +Developers can customize the look and feel of the login page, as well as the identity management system that comes with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/18.0/server_development/#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). diff --git a/vuepress/docs/next/docs/consume/multitenancy.md b/vuepress/docs/next/docs/consume/multitenancy.md index dda605971e..ec50941445 100644 --- a/vuepress/docs/next/docs/consume/multitenancy.md +++ b/vuepress/docs/next/docs/consume/multitenancy.md @@ -1,24 +1,21 @@ --- sidebarDepth: 2 --- - # Entando Multitenancy -## Overview - -An Entando Application can be configured to enable a multitenant architecture where tenants share the infrastructure but are informationally isolated. On Entando v7.3, the full capapbilities of bundles can be utilized in a multitenant environment with installations and data confined to each tenant. +An Entando Application can be configured with multitenant architecture where tenants share an infrastructure but are informationally separate. On Entando v7.3, the full capabilities of bundles can be utilized in a multitenant environment, where tenants share bundles and resources but each exists independently with its own functionality, design, and data. This document provides an overview of multitenancy and Entando's implementation. ## Core Concepts -Multitenancy is an architecture framework in which a single software instance serves multiple tenants. A multitenant application is designed with a common shared infrastructure while data between tenants is segregated. +Multitenancy is an architecture framework in which a single software instance serves multiple tenants. A multitenant application is designed with a shared infrastructure while data between tenants is segregated. -Entando Multitenancy shares Kubernetes, Keycloak, and the Entando Platform infrastructure while distributing resources (CPU, memory) across the primary and secondary tenants for optimal efficiency. Each tenant, identified by a unique domain name, comprises a user group with specific access privileges to the instance. +Entando Multitenancy shares Kubernetes, Keycloak, and the Entando Platform infrastructure while distributing resources (CPU, memory) across the primary and secondary tenants for optimal efficiency. -Each tenant is informationally isolated with its own data, configuration settings, and user management. Kubernetes Secrets are used to protect the confidential parameters of each tenant configurations. +Each tenant, identified by a unique domain name, comprises a user group with specific access privileges to the instance. Each can be designed and developed independently, with segregared data, configuration settings, and user management. Kubernetes Secrets are used to protect the confidential parameters of each tenant configurations. -Data for components and registries connected to a particular tenant is also isolated, with each tenant managing its own set of bundles and registries. When a bundle is installed to a tenant, whether from the Entando Cloud Hub or an enterprise Hub, the bundle is identified as belonging to that tenant by the Component Manager. +Data for components and registries connected to a particular tenant is also isolated, with each tenant managing its own set of bundles and registries. When a bundle is installed to a tenant, whether from the Entando Cloud Hub or an enterprise Hub, it is identified as belonging to that tenant by the Component Manager. ## Architecture @@ -26,14 +23,14 @@ All tenants rely on a single instance of an Entando Application for core functio Redis is necessary for cache management and high availability, which Entando strongly recommends for a multitenant configuration. See the [Redis Integration](../../tutorials/consume/redis.md) tutorial to add it to your Entando Application. -Tenants are differentiated by unique domain names. To isolate its information and configuration, a tenant is allocated each of the following: +Tenants are differentiated by unique domain names. To isolate its information and configuration, a tenant is allocated each of the following resource: - A database or schema for independent data storage - An Entando Content Delivery Server (CDS) instance to manage static resources external to the Entando App Engine - A Solr core to implement an external search engine - A Keycloak client realm to manage user access -![multitenancy.png](./img/multitenancy.png) +![Block diagram for multitenancy services architecture](./img/multitenancy.png) Entando Multitenancy requires that [Solr](../../tutorials/consume/solr.md), [Entando CDS](../../tutorials/consume/cds.md), and [Keycloak](../../tutorials/consume/multitenancy.md#keycloak) are configured for each tenant. diff --git a/vuepress/docs/next/docs/consume/operator-intro.md b/vuepress/docs/next/docs/consume/operator-intro.md index dbbcb17504..b9f664c027 100644 --- a/vuepress/docs/next/docs/consume/operator-intro.md +++ b/vuepress/docs/next/docs/consume/operator-intro.md @@ -1,47 +1,49 @@ +--- +sidebarDepth: 2 +--- # The Entando Operator The Entando Operator processes the custom resources in Kubernetes that represent the different [components of an Entando application](../README.md). -The goal of the operator is to provide automation and a set of default configuration options to simplify and accelerate the deployment of an Entando application. +The goal of the Operator is to provide automation and a set of default configuration options to simplify and accelerate the deployment of an Entando application. -The sections below provide details and assumptions that the operator makes when deploying Entando Custom Resources. If you're using OpenShift, these sections will provide details on how to configure your deployment via the Operator Hub. +The sections below provide details regarding the Operator when Entando Custom Resources are deployed. If you're using OpenShift, these sections provide details on how to configure your deployment via the Operator Hub. -For details on the individual custom resources and their configuration, check out the [custom resources documentation](../reference/custom-resources.md). [See the instructions here on deploying via the Entando Operator](../../tutorials/getting-started/openshift-install-by-operator.md). +For details on the individual custom resource definitions (CRD), check out the [custom resources document](../reference/custom-resources.md). [See the instructions on deploying via the Entando Operator](../../tutorials/getting-started/openshift-install-by-operator.md). ## TLS Secret Creation -When configuring and deploying Entando via the operator, you will be asked to provide a secret for some of the components in the architecture. A few things to be aware of when creating and configuring a Secret: +When configuring and deploying Entando via the Operator, you will be asked to provide a secret for some of the components in the architecture. A few things to be aware of when creating and configuring a Secret: - The Secret is assumed to be in the same namespace as the component being created. - This Secret is expected to have a private key, and a certificate for the hostname (or a wildcard certificate) that the service will be exposed on. -- Refer to the `ingressHostname` property in the custom resource for more information on how the hostname is determined. +- Refer to the `ingressHostName` property in the custom resource for more information on how the hostname is determined. - If a Secret isn't provided, the Entando Operator will evaluate the value of the `ENTANDO_PATH_TO_TLS_KEYPAIR`, which is expected to contain two files: tls.key and tls.crt. - - If a key pair is found in the folder specified, the operator will use that key pair. - - If a key pair is not found, the Entando Operator will evaluate the value of the `ENTANDO_USE_AUTO_CERT_GENERATION`. If that property is set to `true`, the Entando Operator will assume that the cluster has been configured with a valid Certificate Authority (CA) and leave it to the Ingress controller to generate its own certificates. + - If a key pair is found in the folder specified, the Operator will use that key pair. + - If a key pair is not found, the Entando Operator will evaluate the value of the `ENTANDO_USE_AUTO_CERT_GENERATION`. If that property is set to `true`, the Operator will assume that the cluster has been configured with a valid Certificate Authority (CA) and leave it to the Ingress controller to generate its own certificates. -[Click here for instructions on setting up TLS in your Entando Apps](../../tutorials/getting-started/openshift-install-by-operator.md). +[Click here for instructions on setting up TLS for the EntandoApp](../../tutorials/getting-started/openshift-install-by-operator.md). ## Database Deployment Some Entando components include the option to select a database management system (DBMS): -- The value of the DBMS field in Entando Custom Resources can be mysql, oracle, postgresql or embedded. +- The value of the DBMS field in the CRD can be `mysql`, `oracle`, `postgresql`, or embedded. - **IMPORTANT!** -- If embedded is selected for a component, only one replica for the component can be created. This is not recommended for production use. - **IMPORTANT!** -- Oracle instances are not supported for automatic deployment in a container. You must create your own Oracle instance or reuse an existing instance and then configure the [external database](../../tutorials/devops/external-db.md) for your EntandoApp. -- If an EntandoDatabaseService has been deployed in the component's namespace and the DBMS specified for this EntandoDatabaseService is the same as the DBMS specified for this EntandoApp, then the Entando Operator will create dedicated - schemas (in the case of PostgreSQL or Oracle), or databases in the case of MySQL. - - If a matching EntandoDatabaseService does not exist in this namespace, the Entando Operator +- If an `EntandoDatabaseService` has been deployed in the component's namespace and the DBMS specified for this is the same as the DBMS specified for the EntandoApp, then the Operator will create dedicated schemas (in the case of PostgreSQL or Oracle), or databases (in the case of MySQL). + - If a matching `EntandoDatabaseService` does not exist in this namespace, the Operator will automatically deploy the appropriate container to host the DBMS specified. This last option is not yet supported for Oracle. -- For an EntandoApp, three schemas/databases will be created: the Entando Port DB, tne Entando Serv DB and a database for the Entando Component Manager. - - If the Port and Serv schemas/databases are empty, the Entando Operator will use the underlying Entando App to populate these databases with the data backup available in the standard backup path in the WAR deployment. - - In scenarios where the EntandoApp needs to connect to an existing database that is fully managed +- For an EntandoApp, three schemas/databases will be created: the Entando Port DB, Entando Serv DB and a database for the Entando Component Manager. + - If the Port and Serv schemas/databases are empty, the Operator will use the underlying EntandoApp to populate these databases with the data backup available in the standard backup path in the WAR deployment. + - In cases where the EntandoApp needs to connect to an existing database that is fully managed by the customer, it is best to setup the standard database connection variables using the - `spec.environmentVariables` property and set this property to 'none'. This will skip any database - preparations steps in the deployment. + `spec.environmentVariables` property, set to 'none'. This will skip any database + preparation steps in the deployment. -When deploying a component the operator will evaluate the spec and if it supports the standard `spec.dbms` +When deploying a component, the Operator will evaluate the spec, and if it supports the standard `spec.dbms` property, the value of this property will be given to the component's `spec.dbms`. Please consult -the documentation for each component's CRD to determine how each Entando resource uses the dbms (if any). +the documentation for each component's CRD to determine how the Entando resource uses the DBMS (if any). ## Ingress Path Generation diff --git a/vuepress/docs/v7.3/docs/compose/preinstalled-widgets.md b/vuepress/docs/v7.3/docs/compose/preinstalled-widgets.md index 852ec0abf2..ab701dc7ac 100644 --- a/vuepress/docs/v7.3/docs/compose/preinstalled-widgets.md +++ b/vuepress/docs/v7.3/docs/compose/preinstalled-widgets.md @@ -7,7 +7,7 @@ sidebarDepth: 2 The Entando Platform includes a number of useful components to accelerate application development. These consist of widgets, page templates, content templates, and content types. -This page introduces the widgets that are available out of the box with an Entando 7 installation. These widgets are categorized by type, where each type implements CMS, navigation, page, SEO or system functionality. +This page introduces the widgets that are available out of the box with Entando. The widgets are categorized by type, each with its own CMS, navigation, pages, SEO and/or system functionality. ## Widget Attributes @@ -18,12 +18,12 @@ All widgets are required to have the following attributes. These are mandatory r - `Group`: A group for which the user has "create" permissions - `Icon`: A graphic that visually represents the widget via an uploaded icon (SVG file) or one chosen from the icon library - `Custom UI`: HTML code that constructs the visual layout of the widget -- `Config UI`: A JSON structure that informs the widget's configuration. It requires two properties: +- `Config UI`: A JSON structure that defines the widget's configuration. It requires two properties: - `customElement`: The custom element name of the widget config component - `resources`: An array listing the source location of the custom element files for the widget configuration ## Widget Descriptions -The following table lists the notable preinstalled widgets of an Entando instance. They can be accessed from the left menu of the App Builder by selecting `Components` → `MFE & Widgets`. +The following table lists the notable preinstalled widgets of an Entando instance. They are accessible from the left menu of the App Builder by selecting `Components` → `MFE & Widgets`. | Name | Type | Description | @@ -32,12 +32,12 @@ The following table lists the notable preinstalled widgets of an Entando instanc | Content List | CMS | A widget that renders a list of contents, each one displaying information from a template | | Content Search Query | CMS | A widget that publishes a list of contents based on different settings | | Content SEO Meta-description | SEO | A component listing the SEO parameters specified when pages are created or modified | -| Internal Servlet | System | A legacy implementation to create server-side widgets using Struts 2. Available for backwards compatibility with older projects. | +| Internal Servlet | System | A legacy implementation to create server-side widgets using Struts 2. Available for backwards compatibility. | | Legacy Login Form | System | A non-Keycloak form component for logging in | | Legacy Navigation Menu | Navigation | An interface that is configurable via expression list parameters. A user with admin privileges can easily change its layout. | | Login | System | The Keycloak-powered login/logout component for the web app | | Logo | Page | The default Entando logo. It can be used in other projects by changing its fragment reference. | -| Navigation Menu | Navigation | An OOTB widget configurable via expression list parameters | +| Navigation Menu | Navigation | A widget configurable via expression list parameters | | Search Form | CMS | A basic search form | | Search Results | CMS | A component that shows the results of the query entered into the Search Form | diff --git a/vuepress/docs/v7.3/docs/compose/welcome-wizard.md b/vuepress/docs/v7.3/docs/compose/welcome-wizard.md index 5429c568d1..017cb09d6e 100644 --- a/vuepress/docs/v7.3/docs/compose/welcome-wizard.md +++ b/vuepress/docs/v7.3/docs/compose/welcome-wizard.md @@ -1,12 +1,18 @@ +--- +sidebarDepth: 2 +--- + # Welcome Wizard -The Welcome Wizard is displayed when you first log in to the Application Builder. You can also start it later by going to the top navigation bar in the Application Builder, click on the information icon, and click `Begin Welcome Wizard`. You can disable it from the wizard popup by selecting `Don't show next time` and then `Close`, or by going to `My Profile → Preferences` and setting the `Welcome Wizard` preference to `Off`. +The Welcome Wizard is activated and displayed when you first log in to the App Builder. It provides a guided tour of how to begin creating your application. + +If you need to review it at any time, click on the information icon in the top navigation bar, then select `Start Welcome Wizard`. You can slso disable it by checking `Don't show next time` in the popup window, or by going to `My Profile` → `Preferences` and setting the `Welcome Wizard` preference to `Off`. -![./img/welcome-wizard.png](./img/welcome-wizard.png) +![Screenshot-Welcome Wizard popup to create first application](./img/welcome-wizard.png) -The Wizard will guide you through the key steps in designing and publishing a page in your application: +The Wizard will guide you through the key steps in designing and publishing a page for your application. It looks something like this: 1. Create a Page by setting its title, code, location, group, and template. -2. Design the Page by placing a set of pre-configured widgets on the page. +2. Design the Page by placing a set of pre-configured components on the page. 3. Preview the Page 4. Publish the Page diff --git a/vuepress/docs/v7.3/docs/consume/accessibility.md b/vuepress/docs/v7.3/docs/consume/accessibility.md index 45f0e4ae60..89249d10fc 100644 --- a/vuepress/docs/v7.3/docs/consume/accessibility.md +++ b/vuepress/docs/v7.3/docs/consume/accessibility.md @@ -1,9 +1,12 @@ +--- +sidebarDepth: 2 +--- + # Web Accessibility in Entando -> The power of the Web is in its universality. -> Access by everyone regardless of disability is an essential aspect. +**The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect.** -`- Tim Berners-Lee, W3C Director and inventor of the World Wide Web` +-- Tim Berners-Lee, W3C Director and inventor of the World Wide Web Web accessibility means that websites, tools, and technologies are designed and developed so that people with disabilities can use them. Accessibility is essential for developers and organizations that want to create high-quality @@ -12,42 +15,34 @@ See [w3.org](https://www.w3.org/WAI/fundamentals/accessibility-intro/) for an in ## Requirements and Standards -Many projects and programs will have specific requirements in the area of accessibility, particularly for applications +Many projects and programs have specific requirements in terms of accessibility, particularly for applications or sites with a broad reach or specific governance considerations. Entando's approach to accessibility is to provide the tools and techniques that allow a development team to meet their own specific accessibility requirements. -Development teams will need someone to become familiar with the relevant accessibility standards and help make design -decisions on how they will be applied to a specific project. Those standards vary by region so please check the +Development teams need someone to become familiar with the relevant accessibility standards to help make design +decisions on how they can be applied to specific projects. These standards may vary by region so please check the legislation in your area or consult an accessibility specialist. Useful resources include: * [W3C Web Accessibility Initiative (WAI)](https://www.w3.org/WAI/design-develop/) * [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/) * USA: [Section 508 of the Rehabilitation Act](https://www.section508.gov/manage/laws-and-policies) -At the end of the day it's up to a development team to make sure their implementation is compliant with a specific -guideline or standard. Typically a team will make use of Entando Page Templates, Content Templates, and custom micro -frontends in order to accomplish this goal. +At the end of the day, it's up to the development team to make sure their implementation is compliant with specific guidelines or standards. Typically a team will make use of Entando Page Templates, Content Templates, and custom micro frontends in order to accomplish this goal. ## Tools -Accessibility requirements are ideally known at the start of a project so the design language and tools can be adopted -early in the project. Using them consistently will ease implementation of the accessibility elements needed to meet the -desired compliance level. Retrofitting a project for accessibility can be done but is typically more involved. Example +Accessibility requirements are ideally known at the start of a project so the design language and tools can be adopted early in the project. Using them consistently will ease implementation of the accessibility elements needed to meet the desired compliance level. Retrofitting a project for inclusive design can be done but is typically more involved. Example design systems used by Entando clients include: -* [Material-UI](https://material-ui.com/) - a React framework used to build a custom design system and/or one based on - Material Design. +* [Material-UI](https://material-ui.com/) - a React framework used to build a custom design system and/or one based on Material Design. * [Carbon Design System](https://www.carbondesignsystem.com/) - IBM's open source design system * [Bootstrap Italia](https://github.com/italia/bootstrap-italia) - a Bootstrap 4-based frontend theme that implements the Italian Design Guidelines for public websites. -Assessing web accessibility is important throughout the life of a project. There are many tools available in this area. A -useful list can be found [on the W3C site](https://www.w3.org/WAI/ER/tools/) with filters by guideline, region, -language, etc. Entando clients have made good use of the following: +Evaluating web accessibility is important throughout the life of a project. There are many tools available in this area. A useful list can be found [on the W3C site](https://www.w3.org/WAI/ER/tools/) with filters by guideline, region, language, etc. The following resources have been found useful by Entando clients: * [a11y.css](https://chrome.google.com/webstore/detail/a11ycss/iolfinldndiiobhednboghogkiopppid) * [Access Assistant](https://chrome.google.com/webstore/detail/access-assistant/ojiighldhdmahfdnhfdebnpmlbiemdfm) -* [Continuum Explorer Pro](https://chrome.google.com/webstore/detail/continuum-explorer-pro/pgkgokkkoamjdmbnegbedepbhbgecplj) * [Wave (web accessibility evaluation tool)](https://wave.webaim.org/) diff --git a/vuepress/docs/v7.3/docs/consume/entando-apis.md b/vuepress/docs/v7.3/docs/consume/entando-apis.md index e53dc841a2..5d51a62b3c 100644 --- a/vuepress/docs/v7.3/docs/consume/entando-apis.md +++ b/vuepress/docs/v7.3/docs/consume/entando-apis.md @@ -4,7 +4,7 @@ sidebarDepth: 2 # Accessing Entando APIs -Entando includes the Swagger UI for API access in a quickstart environment. This document presents an overview and instructions on how to enable and access the Swagger UI. +Entando includes the Swagger UI for API access in a quickstart environment. This document presents an overview, and instructions on how to enable and utilize the interface. ## APIs Overview The Entando App Engine uses REST APIs to enact all the functionality inside the App Builder. For example, APIs are used to add widgets to a page or create components like pages and page templates. APIs can also be used to support automation, testing, and integration with external systems. @@ -19,13 +19,14 @@ All of the model classes returned by the Entando App Engine are annotated with d ## Enable the Swagger UI -The Swagger UI can be enabled or disabled in a running Entando instance by modifying the `SPRING_PROFILES_ACTIVE` environment variable for the `entando-de-app` container. +The Swagger UI can be enabled or disabled in a running Entando instance by modifying the environment variable `SPRING_PROFILES_ACTIVE` in the `entando-de-app` container. 1. (Optional) Scale the deployment `spec.replicas` to 0. >This is necessary if you're using an in-memory database as in the default quickstart configuration. This will prevent database errors on immediate restarts when the deployment is changed. -2. Edit the `entando-de-app` deployment. If you have different names for deployment and namespace, adjust the command below accordingly. +2. Edit the `entando-de-app` deployment. If you have different names for namespace and deployment, adjust the command accordingingly. + >Use the [ent CLI](../getting-started/entando-cli.md) to send commands to Kubernetes from the host machine. ``` @@ -46,16 +47,16 @@ kubectl -n entando edit deployment/quickstart-deployment Repeat the steps above, but in step 4, remove `swagger` from the value list. -## Find Your Client Secret +## Retrieve Your Client Secret You'll need your client credentials to execute Entando APIs. -1. Log in into your Keycloak Administration Console at `http://[YOUR-HOST-NAME]/auth`. To find the Keycloak admin credentials, see the [Entando Identity Management System](./identity-management.md) page. +1. Log in to your Keycloak Administration Console at `http://[YOUR-HOST-NAME]/auth`. To find the Keycloak admin credentials, see the [Entando Identity Management System](./identity-management.md) page. 2. From the left navigation panel, go to `Clients` 3. Select the desired client (e.g. in a quickstart environment, this is `quickstart`) -4. Click on the `Credentials` tab to retrieve the Secret. Save the `Client Id` and `Secret` for the steps below. +4. Click on the `Credentials` tab to find the Secret. Save the `Client Id` and `Secret` for the steps below. ## Access the APIs on Swagger 1. To see the APIs, go to: @@ -65,7 +66,7 @@ http://[YOUR-HOST-NAME]/entando-de-app/api/swagger-ui.html 2. Click on the Authorize button in the upper right corner. -3. Enter the client ID and Secret from above. Click Authorize. +3. Enter the `Client ID` and `Secret` from above. Click `Authorize`. 4. You will be prompted to log in to your Keycloak instance as an Entando admin user if you have not already done so. The default credentials are admin/adminadmin. diff --git a/vuepress/docs/v7.3/docs/consume/high-avail-application.md b/vuepress/docs/v7.3/docs/consume/high-avail-application.md index 9112fe71bf..c4f931714e 100644 --- a/vuepress/docs/v7.3/docs/consume/high-avail-application.md +++ b/vuepress/docs/v7.3/docs/consume/high-avail-application.md @@ -1,3 +1,6 @@ +--- +sidebarDepth: 2 +--- # High Availability in an Entando Application ## App Engine Clustering and High Availability @@ -6,7 +9,7 @@ The Entando App Engine can be deployed as a clustered set of instances using the This document examines the issues to consider when creating highly availailable clusters of the Entando App Engine. -Microservices clustering that adds functionality to an Entando Application is different from clustering used by the Entando App Engine. Microservices rely on a custom clustering configuration and setup based on implementation and selections made during their creation. Refer to documentation addressing [clustered microservices and caching implementation](../../tutorials/consume/high-availability.md) for configuration and deployment details. +Microservices clustering that adds functionality to an Entando Application is different from clustering used by the Entando App Engine. Microservices rely on a custom clustering configuration and setup based on implementation, and selections made during their creation. Refer to the documentation addressing [clustered microservices and caching implementation](../../tutorials/consume/high-availability.md) for more details. ::: tip @@ -31,18 +34,18 @@ The following objects are cached in the base implementation of the Entando App E - Languages - Labels (i18n) - User profiles -- API Catalog (legacy API metadata separate from swagger) +- API Catalog (legacy API metadata separate from Swagger) - Data models and data types (deprecated) ## Redis Implementation -An Entando Application can be configured to utilize an external [Redis](https://redis.io/) cache. In a Redis implementation of an Entando Application, the cache is deployed independently of the Entando App Engine and the App Engine is configured to connect to the deployed instance. +An Entando Application can be configured to utilize an external [Redis](https://redis.io/) cache. In a Redis implementation of an Entando Application, the cache is deployed independently of the Entando App Engine and the Engine is configured to connect to the deployed instance. -![Redis Caching](./img/redis-caching.png) +![Entando Architecture with Redis Caching](./img/redis-caching.png) The Redis cache is not deployed by the Entando Operator and must be managed by a DevOps team member or Kubernetes cluster administrator. -Check out the [High Availability on Entando tutorial](../../tutorials/consume/high-availability.md#clustering) for more information and step-by-step instructions to use a Redis cache in an Entando Application. +Check out the [High Availability on Entando tutorial](../../tutorials/consume/high-availability.md#clustering) for more information and step-by-step instructions on using a Redis cache. ## Performance diff --git a/vuepress/docs/v7.3/docs/consume/identity-management.md b/vuepress/docs/v7.3/docs/consume/identity-management.md index 23d9753311..a7787bb633 100644 --- a/vuepress/docs/v7.3/docs/consume/identity-management.md +++ b/vuepress/docs/v7.3/docs/consume/identity-management.md @@ -1,6 +1,9 @@ +--- +sidebarDepth: 2 +--- # Entando Identity Management System -The Entando Identity Management System is based on open source Keycloak. Entando Applications rely on a Keycloak instance that is either [externally installed](../../tutorials/consume/external-id-management.md) or specific to an application. The architecture and requirements to customize your Keycloak instance are described below. +The Entando Identity Management System is based on the open source Keycloak identity and access management system. Entando Applications rely on a Keycloak instance that is either [externally installed](../../tutorials/consume/external-id-management.md) or specific to an application. The architecture and requirements to customize your Keycloak instance are described below. ## Logging into your Keycloak Instance @@ -20,33 +23,34 @@ kubectl get secrets -n entando ## Authentication All authentication is powered by Keycloak on Entando. This ensures that a micro frontend can call a microservice with a token available to the client. -![Init Containers Screenshot](./img/keycloak-arch-high-level.png) +![Entando cluster & Keycloak architecture diagram with JWT tokens](./img/keycloak-arch-high-level.png) -Entando implements Keycloak as a central point of authentication to provide a single, unified view of identity. This architecture increases portability. Keycloak acts as an abstraction layer to the underlying Identity Provider (IDP), allowing Entando to integrate into other IDPs without modifying the source. +Entando implements Keycloak as a central point of authentication to provide a single unified view of identity. This infrastructure increases portability. Keycloak acts as an abstraction layer to the underlying Identity Provider (IDP), allowing Entando to integrate into other IDPs without modifying the source. ## Authorization ### Role Assignment for Plugins/Microservices Keycloak authorizes microservices using clients and roles. Authorizations are stored in a JSON Web Token and available to services when invoked. -Below are the steps to grant a user one or more roles for a specific client. This controls permissions when configuring the microservice. Note: when a microservice is installed in Entando, a corresponding client (and set of roles) is created per its plugin definition. +Below are the steps to grant a user one or more roles for a specific client. This controls permissions when configuring the microservice. Note, when a microservice is installed in Entando, a corresponding client (and set of roles) is created within its plugin definition. -1. [Login to Keycloak](#logging-into-your-keycloak-instance), which for non-external Keycloak instances is [the base URL of your running Entando application](../getting-started/README.md#configure-access-to-your-cluster) followed by `/auth/`, e.g. http://YOUR-HOST-NAME/auth. In a standard Entando installation, the base URL can be verified with `kubectl get ingress/default-sso-in-namespace-ingress`. -2. Select `Users` from the menu on the left +1. [Login to Keycloak](#logging-into-your-keycloak-instance) +>For non-external Keycloak instances, it is [the base URL of your running Entando application](../getting-started/README.md#configure-access-to-your-cluster) followed by `/auth/`, e.g. http://YOUR-HOST-NAME/auth. In a standard Entando installation, the base URL can be verified with `kubectl get ingress/default-sso-in-namespace-ingress`. +2. Select `Users` from the left menu 3. Use the search box to find the appropriate user, e.g. "admin" 4. Click on the user ID -![find-admin.png](./img/find-admin.png) +![Screenshot-AppBuilder Users Lookup for admin](./img/find-admin.png) -5. Click on the `Role Mappings` tab +5. Click the `Role Mappings` tab 6. Use the `Client Roles` drop-down menu to specify the microservice client 7. Select from the client's `Available Roles` -![find-roles.png](./img/find-roles.png) +![Screenshot-Client Roles Dropdown of Available Roles](./img/find-roles.png) 8. Use the `Add Selected` button to move the desired roles to `Assigned Roles`. These will subsequently appear under `Effective Roles`. -![assign-roles.png](./img/assign-roles.png) +![Screenshot-Roles added to Effective Roles](./img/assign-roles.png) ### Core When a user is authenticated to the `entando-core` via Keycloak, a copy of that user is added to the `entando-core` user management database to enable WCMS functionality. Within the App Builder, WCMS roles and groups can be assigned to a user for access to App Builder functions or `portal-ui` content in the runtime application. @@ -60,8 +64,8 @@ Keycloak allows Entando to provide social login as an out-of-the-box capability. ## One Time Passwords -Keycloak enables One Time Passwords (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/18.0/server_admin/index.html#one-time-password-otp-policies) to configure and enable OTP in your application. +Keycloak enables One Time Password (OTP) login to Entando Applications. See [Keycloak OTP Policies](https://www.keycloak.org/docs/18.0/server_admin/index.html#one-time-password-otp-policies) to configure and enable it. ## Themes, Look and Feel -Developers can customize the look and feel of the login page, as well as the identity management system that ships with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/18.0/server_development/#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). +Developers can customize the look and feel of the login page, as well as the identity management system that comes with Entando. The [Keycloak Theme Documentation](https://www.keycloak.org/docs/18.0/server_development/#_themes) provides instructions for creating your own theme. Alternatively, you can modify the [Entando Theme](https://github.com/entando/entando-keycloak/tree/master/themes/entando). diff --git a/vuepress/docs/v7.3/docs/consume/multitenancy.md b/vuepress/docs/v7.3/docs/consume/multitenancy.md index dda605971e..ec50941445 100644 --- a/vuepress/docs/v7.3/docs/consume/multitenancy.md +++ b/vuepress/docs/v7.3/docs/consume/multitenancy.md @@ -1,24 +1,21 @@ --- sidebarDepth: 2 --- - # Entando Multitenancy -## Overview - -An Entando Application can be configured to enable a multitenant architecture where tenants share the infrastructure but are informationally isolated. On Entando v7.3, the full capapbilities of bundles can be utilized in a multitenant environment with installations and data confined to each tenant. +An Entando Application can be configured with multitenant architecture where tenants share an infrastructure but are informationally separate. On Entando v7.3, the full capabilities of bundles can be utilized in a multitenant environment, where tenants share bundles and resources but each exists independently with its own functionality, design, and data. This document provides an overview of multitenancy and Entando's implementation. ## Core Concepts -Multitenancy is an architecture framework in which a single software instance serves multiple tenants. A multitenant application is designed with a common shared infrastructure while data between tenants is segregated. +Multitenancy is an architecture framework in which a single software instance serves multiple tenants. A multitenant application is designed with a shared infrastructure while data between tenants is segregated. -Entando Multitenancy shares Kubernetes, Keycloak, and the Entando Platform infrastructure while distributing resources (CPU, memory) across the primary and secondary tenants for optimal efficiency. Each tenant, identified by a unique domain name, comprises a user group with specific access privileges to the instance. +Entando Multitenancy shares Kubernetes, Keycloak, and the Entando Platform infrastructure while distributing resources (CPU, memory) across the primary and secondary tenants for optimal efficiency. -Each tenant is informationally isolated with its own data, configuration settings, and user management. Kubernetes Secrets are used to protect the confidential parameters of each tenant configurations. +Each tenant, identified by a unique domain name, comprises a user group with specific access privileges to the instance. Each can be designed and developed independently, with segregared data, configuration settings, and user management. Kubernetes Secrets are used to protect the confidential parameters of each tenant configurations. -Data for components and registries connected to a particular tenant is also isolated, with each tenant managing its own set of bundles and registries. When a bundle is installed to a tenant, whether from the Entando Cloud Hub or an enterprise Hub, the bundle is identified as belonging to that tenant by the Component Manager. +Data for components and registries connected to a particular tenant is also isolated, with each tenant managing its own set of bundles and registries. When a bundle is installed to a tenant, whether from the Entando Cloud Hub or an enterprise Hub, it is identified as belonging to that tenant by the Component Manager. ## Architecture @@ -26,14 +23,14 @@ All tenants rely on a single instance of an Entando Application for core functio Redis is necessary for cache management and high availability, which Entando strongly recommends for a multitenant configuration. See the [Redis Integration](../../tutorials/consume/redis.md) tutorial to add it to your Entando Application. -Tenants are differentiated by unique domain names. To isolate its information and configuration, a tenant is allocated each of the following: +Tenants are differentiated by unique domain names. To isolate its information and configuration, a tenant is allocated each of the following resource: - A database or schema for independent data storage - An Entando Content Delivery Server (CDS) instance to manage static resources external to the Entando App Engine - A Solr core to implement an external search engine - A Keycloak client realm to manage user access -![multitenancy.png](./img/multitenancy.png) +![Block diagram for multitenancy services architecture](./img/multitenancy.png) Entando Multitenancy requires that [Solr](../../tutorials/consume/solr.md), [Entando CDS](../../tutorials/consume/cds.md), and [Keycloak](../../tutorials/consume/multitenancy.md#keycloak) are configured for each tenant. diff --git a/vuepress/docs/v7.3/docs/consume/operator-intro.md b/vuepress/docs/v7.3/docs/consume/operator-intro.md index dbbcb17504..b9f664c027 100644 --- a/vuepress/docs/v7.3/docs/consume/operator-intro.md +++ b/vuepress/docs/v7.3/docs/consume/operator-intro.md @@ -1,47 +1,49 @@ +--- +sidebarDepth: 2 +--- # The Entando Operator The Entando Operator processes the custom resources in Kubernetes that represent the different [components of an Entando application](../README.md). -The goal of the operator is to provide automation and a set of default configuration options to simplify and accelerate the deployment of an Entando application. +The goal of the Operator is to provide automation and a set of default configuration options to simplify and accelerate the deployment of an Entando application. -The sections below provide details and assumptions that the operator makes when deploying Entando Custom Resources. If you're using OpenShift, these sections will provide details on how to configure your deployment via the Operator Hub. +The sections below provide details regarding the Operator when Entando Custom Resources are deployed. If you're using OpenShift, these sections provide details on how to configure your deployment via the Operator Hub. -For details on the individual custom resources and their configuration, check out the [custom resources documentation](../reference/custom-resources.md). [See the instructions here on deploying via the Entando Operator](../../tutorials/getting-started/openshift-install-by-operator.md). +For details on the individual custom resource definitions (CRD), check out the [custom resources document](../reference/custom-resources.md). [See the instructions on deploying via the Entando Operator](../../tutorials/getting-started/openshift-install-by-operator.md). ## TLS Secret Creation -When configuring and deploying Entando via the operator, you will be asked to provide a secret for some of the components in the architecture. A few things to be aware of when creating and configuring a Secret: +When configuring and deploying Entando via the Operator, you will be asked to provide a secret for some of the components in the architecture. A few things to be aware of when creating and configuring a Secret: - The Secret is assumed to be in the same namespace as the component being created. - This Secret is expected to have a private key, and a certificate for the hostname (or a wildcard certificate) that the service will be exposed on. -- Refer to the `ingressHostname` property in the custom resource for more information on how the hostname is determined. +- Refer to the `ingressHostName` property in the custom resource for more information on how the hostname is determined. - If a Secret isn't provided, the Entando Operator will evaluate the value of the `ENTANDO_PATH_TO_TLS_KEYPAIR`, which is expected to contain two files: tls.key and tls.crt. - - If a key pair is found in the folder specified, the operator will use that key pair. - - If a key pair is not found, the Entando Operator will evaluate the value of the `ENTANDO_USE_AUTO_CERT_GENERATION`. If that property is set to `true`, the Entando Operator will assume that the cluster has been configured with a valid Certificate Authority (CA) and leave it to the Ingress controller to generate its own certificates. + - If a key pair is found in the folder specified, the Operator will use that key pair. + - If a key pair is not found, the Entando Operator will evaluate the value of the `ENTANDO_USE_AUTO_CERT_GENERATION`. If that property is set to `true`, the Operator will assume that the cluster has been configured with a valid Certificate Authority (CA) and leave it to the Ingress controller to generate its own certificates. -[Click here for instructions on setting up TLS in your Entando Apps](../../tutorials/getting-started/openshift-install-by-operator.md). +[Click here for instructions on setting up TLS for the EntandoApp](../../tutorials/getting-started/openshift-install-by-operator.md). ## Database Deployment Some Entando components include the option to select a database management system (DBMS): -- The value of the DBMS field in Entando Custom Resources can be mysql, oracle, postgresql or embedded. +- The value of the DBMS field in the CRD can be `mysql`, `oracle`, `postgresql`, or embedded. - **IMPORTANT!** -- If embedded is selected for a component, only one replica for the component can be created. This is not recommended for production use. - **IMPORTANT!** -- Oracle instances are not supported for automatic deployment in a container. You must create your own Oracle instance or reuse an existing instance and then configure the [external database](../../tutorials/devops/external-db.md) for your EntandoApp. -- If an EntandoDatabaseService has been deployed in the component's namespace and the DBMS specified for this EntandoDatabaseService is the same as the DBMS specified for this EntandoApp, then the Entando Operator will create dedicated - schemas (in the case of PostgreSQL or Oracle), or databases in the case of MySQL. - - If a matching EntandoDatabaseService does not exist in this namespace, the Entando Operator +- If an `EntandoDatabaseService` has been deployed in the component's namespace and the DBMS specified for this is the same as the DBMS specified for the EntandoApp, then the Operator will create dedicated schemas (in the case of PostgreSQL or Oracle), or databases (in the case of MySQL). + - If a matching `EntandoDatabaseService` does not exist in this namespace, the Operator will automatically deploy the appropriate container to host the DBMS specified. This last option is not yet supported for Oracle. -- For an EntandoApp, three schemas/databases will be created: the Entando Port DB, tne Entando Serv DB and a database for the Entando Component Manager. - - If the Port and Serv schemas/databases are empty, the Entando Operator will use the underlying Entando App to populate these databases with the data backup available in the standard backup path in the WAR deployment. - - In scenarios where the EntandoApp needs to connect to an existing database that is fully managed +- For an EntandoApp, three schemas/databases will be created: the Entando Port DB, Entando Serv DB and a database for the Entando Component Manager. + - If the Port and Serv schemas/databases are empty, the Operator will use the underlying EntandoApp to populate these databases with the data backup available in the standard backup path in the WAR deployment. + - In cases where the EntandoApp needs to connect to an existing database that is fully managed by the customer, it is best to setup the standard database connection variables using the - `spec.environmentVariables` property and set this property to 'none'. This will skip any database - preparations steps in the deployment. + `spec.environmentVariables` property, set to 'none'. This will skip any database + preparation steps in the deployment. -When deploying a component the operator will evaluate the spec and if it supports the standard `spec.dbms` +When deploying a component, the Operator will evaluate the spec, and if it supports the standard `spec.dbms` property, the value of this property will be given to the component's `spec.dbms`. Please consult -the documentation for each component's CRD to determine how each Entando resource uses the dbms (if any). +the documentation for each component's CRD to determine how the Entando resource uses the DBMS (if any). ## Ingress Path Generation