diff --git a/vuepress/docs/next/docs/curate/ecr-troubleshooting-guide.md b/vuepress/docs/next/docs/curate/ecr-troubleshooting-guide.md index d88d598461..5b1d147177 100644 --- a/vuepress/docs/next/docs/curate/ecr-troubleshooting-guide.md +++ b/vuepress/docs/next/docs/curate/ecr-troubleshooting-guide.md @@ -1,38 +1,36 @@ # Troubleshooting ECR -## A bundle installation/removal has failed, how to access the logs? +## How do I access the logs? +**A bundle installation or removal has failed. How do I access the logs?** -### Overview +Currently the Entando Component Manager logs are only available in Kubernetes through Openshift dashboards or CLI tools like K9s and kubectl. -Currently the Entando component manager logs are available in kubernetes via dashboard (openshift) or cli tools (k9s or kubectl). -If in you Entando cluster you have more than one Entando App custom resource, you will need to know what's the correct component-manager to check using the corresponding Entando App name and namespace where the app has been deployed. ### Solution - -Using `kubectl` and assuming for simplicity that you have only one Entando App named `quickstart` and your Entando cluster is only composed of one namespace, also named `quickstart`, -you can get the component-manager logs using the command +If your Entando cluster has more than one Entando App custom resource, find the component manager in question using the Entando App name and namespace where the app has been deployed. Assuming you have a single Entando App named `quickstart` and your cluster namespace is called `YOUR-NAMESPACE`, +retrieve the component manager logs using this command: ``` -kubectl logs -f deployment/quickstart-server-deployment --namespace quickstart -c de-container +kubectl logs -f deployment/quickstart-server-deployment --namespace YOUR-NAMESPACE -c de-container ``` -**Note**: the `-f` flag is optional and could be used to follow the logs for debugging purposes +Note the `-f` flag is optional and used to follow the logs for debugging purposes. -## My bundle has an issue, how should I publish a new version of the bundle? +## How do I publish a new version +**My bundle has an issue. How do I publish a new version of the bundle?** -### Overview -Sometimes a bundle could have some issues: typos in the `descriptor.yaml` file, wrong references of components or to not available docker images are just a few of the possible errors. +Sometimes a bundle could have issues such as typos in the descriptor.yaml, faulty references for components, or unavailable Docker images. After making the corrections, your bundle will need to be updated. ### Solution -1. If the bundle is shared using a git repository, you can make the required changes to your project and publish the new version to git and generate a new tag for it. -2. Once the new tag is published, update the bundle costum-resource avaialble in you Entando Cluster by adding the new tag to the `tags` objects and replacing the latest `dist-tags` to point to this new version. -3. Proceed with the new installation +1. If the bundle is shared in a Git repository, you can make the required changes to your project, publish the new version to Git, and generate a new tag for it. +2. Once the new tag is published, update the bundle custom resource in the cluster by adding the new tag to the `tags` object and replacing the latest `dist-tags` to point to the new version. +3. Then proceed with the new installation. -If you're actively working on your bundle and you simply want to verify things are working correctly, instead of generating a new tag for each release of the bundle you can try to keep overriding a specific tag using the git command `git tag -f`. We suggest you to follow this practice only during development and not in production. +Note: If you're actively working on your bundle and simply want to verify that things are working correctly, you can override a specific tag using the Git command `git tag -f` instead of generating a new tag for each release of the bundle. You should follow this practice only during development, never in production. -## Bundle installation fails because a file has not been found in the bundle +## ERROR - File not found in bundle +**Installation fails because a file has not been found in the bundle** -### Overview -When a component that is referenced in the `descriptor.yaml` is missing in the bundle or not correctly referenced, the bundle installation fails and in the logs is reported which file has not been found. +When a component that is referenced in the descriptor.yaml is missing in the bundle or not properly called, the bundle installation will fail and the error reported in the logs. ``` ERROR - File with name {filename} not found in the bundle @@ -40,31 +38,27 @@ ERROR - File with name {filename} not found in the bundle ### Solution -When such a problem happens, verify that the component referenced in the descriptor file are actually present in the bundle and that the reference is properly typed. +Verify that the component named in the descriptor file is actually present in the bundle, in the location specified, and that the reference is properly formatted. -Publish a new version of your bundle as described in the -["My bundle has an issue"](#my-bundle-has-an-issue-how-should-i-publish-a-new-version-of-the-bundle) section +Then +[publish a new bundle version](#how-do-i-publish-a-new-version) as explained above. -## Bundle installation failed due to plugin(s) images not reachable +## My plugin Docker image is unreachable +**Bundle installation fails due to plugin images that are not reachable** -### Overview -Plugin included in a bundle are referenced using their docker image. Sometime the image is not available - maybe has not yet be published or is in a private docker registry - and plugin installation can't happen and the entire bundle installation process can't finish successfully +A bundle installation does not complete successfully because a plugin in a bundle, defined by a Docker image, is not available. ### Solution +This may happen if the Docker image for the plugin is located in a private registry or not yet published. Verify that the Docker image you are referencing is published, correctly formatted, and publicly available. -Verify that the docker image you are referencing is correct and publicly available. - -["My bundle has an issue"](#my-bundle-has-an-issue-how-should-i-publish-a-new-version-of-the-bundle) section - -## I can't uninstall a bundle because some components are in use +Then +[publish a new bundle version](#how-do-i-publish-a-new-version) as explained above. -### Overview +## How do I uninstall a bundle +**I can't uninstall a bundle because some components are in use** -When removing an installed bundle, the Entando component manager verfies that the bundle components -are not in use by any other component. Removing such components would cause an error during removal -as in certain case the deleting a component in use is not permitted. +When uninstalling an installed bundle, the Entando Component Manager verfies that the bundle components are not in use by any other component. An error message informs you and does not allow the removal. ### Solution -In order to prevent such errors, the user is alerted and required to manually decouple the bundle -components before beign able to completely remove the bundle from the system. +A bundle cannot be uninstalled if any of its components are in use. To uninstall the bundle, the user must manually remove all references to it and all its component. \ No newline at end of file diff --git a/vuepress/docs/next/docs/reference/deployment-structure.md b/vuepress/docs/next/docs/reference/deployment-structure.md index b7ff010464..cf039913a7 100644 --- a/vuepress/docs/next/docs/reference/deployment-structure.md +++ b/vuepress/docs/next/docs/reference/deployment-structure.md @@ -4,156 +4,130 @@ sidebarDepth: 2 # Entando Deployment Structure -This page provides a high level overview of the key Entando GitHub repositories along with a brief description -of how those repositories are realized in a running Entando deployment. The descriptions provided here are meant -as a guide for identifying opportunities to dig deeper into the architecture and how things are structured -rather than a panacea for understanding the architecture. +This page provides an overview of the key Entando GitHub repositories with brief descriptions +of how these repositories are realized in a running Entando deployment. It also explores the architecture behind the Entando Platform and how its functions are structured. ## entando-operator -The Entando operator coordinates the installation and configuration of all of the components of an Entando -Cluster. The operator can be installed once per Entando Cluster and used to coordinate the plugin lifecycle for -multiple Entando applications across many namespaces. +The Entando Operator coordinates the installation and configuration of all the components in an Entando +cluster. The operator can be installed once per cluster and is used to coordinate the plugin lifecycle for multiple Entando Applications across many namespaces. * GitHub: * DockerHub: #### Customization -It is unlikely that the operator will be customized as part of an Entando implementation. It is not built to -be extended inside the codebase. The most common pattern will be to use the existing custom resources that the -operator knows how to deploy to extend the Entando platform. +Use existing [Entando Custom Resources](../consume/custom-resources.md) to extend the Entando Platform. -## database init containers -During installation, an Entando application needs to create several databases and initialize those -databases with information when deploying from a backup in your images. At initialization, the _entando-k8s-dbjob_ -will be run 5 times in total. Once for keycloak, twice for the entando application (port and serv dbs), once to -populate the Entando application database, and once to create the Component Repository database. +## Database Init Containers +During installation, an Entando Application needs to create and initialize several databases when deploying from a backup of your images. * GitHub: * DockerHub: -The screenshot below highlights the init containers for the Entando application schema creation, db -initialization, and component repository database. +The screenshot below highlights the init containers for the Entando Application schema creation, DB initialization, and component repository database. ![Init Containers Screenshot](./img/init-containers-screenshot.png) -Many managed kubernetes instances like OpenShift won’t show init containers in their dashboards. So if you’re -troubleshooting you may need to look deeper. When fetching logs for an init container using kubectl, you must -pass the container name as an argument to the call. For example, +Many managed Kubernetes instances like OpenShift don’t display init containers on their dashboards. If you’re troubleshooting, the logs may provide some useful information. To fetch logs for an init container using kubectl, you must +pass the container name as an argument. - kubectl logs -c -n +For example: + + kubectl logs YOUR-POD -c YOUR-CONTAINER-NAME -n YOUR-NAMESPACE kubectl logs default-sso-in-namespace-deployment-db-preparation-job-ddbdbddb-a -c default-sso-in-namespace-deployment-db-schema-creation-job -n sprint1-rc #### Customization -It is unlikely that the init containers will be customized as part of an Entando project. The init containers -will automatically restore a backup included in your application so that you can create custom images that -include your application setup. -See [Backing Up and Restoring Your Environment](../../tutorials/devops/backing-up-and-restoring-your-environment.md). +The init containers automatically restore a backup included in your application so that you can create custom images with your application setup. +See [Backing Up and Restoring Your Environment](../../tutorials/devops/backing-up-and-restoring-your-environment.md) for more details. ## entando-de-app -The _entando-de-app_ is a J2EE application and is an instance of the _entando-core_ (see a description of the -_entando-core_ repo below). Reviewing the dependencies of this application in the pom.xml will reveal the -dependencies on the _entando-core_, _entando-engine_, and _admin-console_ which encompass the core -functionality in versions of Entando prior to Entando 6. In a quickstart deployment the _entando-de-app_ is deployed as part of the _entando-composite-app_ multi -container pod. +The **entando-de-app** is a J2EE application and an instance of the [**entando-core**](#entando-core). It provides pathways for other Entando Components and the server image the Entando Operator requires to manage the deployment. The pom.xml for the application reveals its dependencies. + * GitHub: * DockerHub: , #### Customization -The _entando-de-app_ is very likely to be customized as part of an Entando implementation. This image can be -customized with new APIs, legacy Entando plugins, new database tables, or other extensions to the _entando-core_. -It is highly recommended that most extensions to the platform on Entando occur in microservices. However, legacy -integrations, extensions to the CMS, and migrations from earlier Entando versions may require changes to the _entando-de-app_. - -## app-builder -The _app-builder_ is the front end of the _entando-de-app_. It communicates with the _entando-de-app_ via [REST -APIs](../consume/entando-apis.md). The _app-builder_ is a React JS application and is served via node in the default -deployment. In a quickstart deployment, the _app-builder_ container is deployed in the _entando-app_ -multiple container pod. The _app-builder_ also communicates with the Component Manager via REST API to fetch -information about Entando bundles deployed to the Entando Component Repository (ECR). +The **entando-de-app** is very likely to be customized as part of an Entando implementation. +A customized image can include: +* New APIs +* Legacy Entando plugins +* New database tables +* Other extensions to the **entando-core** + +It is recommended that most extensions to the Entando Platform occur in microservices. However, legacy +integrations, extensions to the CMS, and migrations from earlier Entando versions may require changes to the **entando-de-app**. + +## App Builder +The App Builder is the user-friendly frontend UI for the **entando-de-app**. A ReactJS application, it is served via node in the default deployment. In a quickstart deployment, the App Builder container is deployed in the **entando-app** multi-container pod. It communicates with the **entando-de-app** and the Entando Component Manager (ECM) via [REST +APIs](../consume/entando-apis.md). The ECM provides information about bundles deployed to the Entando Component Repository (ECR). * GitHub: * DockerHub: #### Customization -The _app-builder_ is customized as part of many Entando implementations. +The App Builder is customized as part of many Entando implementations. It can be customized at runtime via micro frontends [widget configuration](../../tutorials/create/mfe/widget-configuration.md). -## component-manager(cm) -The _component-manager_ provides the link between the entando-de-app (or your custom core instance) and the ECR. The _component-manager_ queries the entando-k8s service to fetch available -bundles that have been deployed as custom resources inside of an Entando cluster. -The _component-manager_ also manages the relationships between an Entando application and the -installed plugins. This can be seen in the plugin link custom resources in Kubernetes. +## Entando Component Manager (ECM) +The ECM provides the link between the **entando-de-app**, or your custom core instance, and the ECR. The ECM queries the Entando Kubernetes service to fetch available +bundles that have been deployed as custom resources inside the cluster. + +The ECM also manages relationships between an Entando Application and the +installed plugins. This can be seen in the plugin link custom resource in Kubernetes. * GitHub: * DockerHub: -#### Customization -It is unlikely that the _component-manager_ will be customized as part of an Entando implementation. - ## entando-k8s-service -The _entando-k8s-service_ acts as an abstraction layer to fetch data from kubernetes APIs. The primary -functionality is in discovering and making available for installation Entando plugins. The -_entando-k8s-service_ is invoked by the _component-manager_. +The **entando-k8s-service** acts as an abstraction layer to fetch data from Kubernetes APIs. Its primary +function is to discover and make available Entando plugins for installation. The +**entando-k8s-service** is invoked by the ECM. * GitHub: * DockerHub: -#### Customization -It is very unlikely that the _entando-k8s-service_ will be customized as part of an Entando implementation. - -## keycloak -The _entando-keycloak_ project is an extension of the base Keycloak images. The extension provides the default -themes for Entando, a customized realm and clients, and adds the Oracle ojdbc jars for connection to Oracle -databases. +## Keycloak +The **entando-keycloak** project is an extension of the base Keycloak images. It provides default themes for Entando, a customized realm and clients, and Oracle JDBC JARs for connecting to Oracle databases. * GitHub: * DockerHub: #### Customization -The keycloak image will often be customized as part of an Entando implementation. Common extensions will -include changing the theme, adding default connections, adding default social logins, adding default clients, -or other changes. +The Keycloak image can be customized as part of an Entando implementation. Some common extensions are: +* Change the theme +* Add default connections +* Add default social logins +* Add default clients ## Other Key Repositories ### entando-core -The entando-core project is a J2EE application that exposes APIs for the Entando CMS, includes the legacy -admin console, and includes the portal-ui project that performs the server side composition for pages -rendered via an Entando application. Note that only the composition is performed server side. -Javascript code is rendered on the client. The entando-core is realized via an instance that includes the -WAR files generated from a core build as dependencies. In a default deployment this is the _entando-de-app_. +The **entando-core** project is a J2EE application that exposes APIs for the Entando CMS, including the admin console and the portal UI project that performs the server side composition for pages rendered via an Entando Application. Note that only the composition is performed server side. JavaScript code is rendered client-side. The **entando-core** is realized via an instance that includes the +WAR files generated from a core build as dependencies. In a default deployment, this is the **entando-de-app**. * GitHub: * DockerHub: None (deployed to maven central) #### Customization -For users familiar with versions prior to Entando 6, there will be cases where the _entando-core_ is customized. -In most cases, these customizations will be delivered via a WAR overlay in the instance project. +For users familiar with versions prior to Entando 6, there will be cases where the **entando-core** is customized. +Often, these customizations will be delivered via a WAR overlay in the instance project. Using a WAR overlay is a functional approach for users already familiar with the process, but it is highly recommended to extend the platform using microservices for new projects. ### entando-cms -The _entando-cms_ project is the _app-builder_ (React JS) side of the Entando WCMS. It is bundled into the -_app-builder_ at build time and will be included in the default deployment of the _app-builder_ in almost all cases. +The **entando-cms** project is the App Builder (ReactJS) side of the Entando WCMS. It is bundled into the +App Builder at build time and is included in the default deployment of the App Builder in most cases. * GitHub: * DockerHub: None (deployed to npm) #### Customization -In some cases the _entando-cms_ may be customized if new custom features are added to CMS specific -functionality. However, most cases will use the more general _app-builder_ extension points noted above. -The _entando-cms_ does not expose any dedicated extension interfaces outside of those already provided by the -_app-builder_. - -### entando-components -The entando-components project is a collection of legacy plugins for Entando 5 and earlier. These plugins are deployed as WAR dependencies in an entando-core instance. -* GitHub: -* DockerHub: None (deployed to maven central) +In some cases, the **entando-cms** may be customized if new custom features are added to CMS-specific +functionality. However, most cases will use the more general App Builder extension points noted above. The **entando-cms** does not expose any dedicated extension interfaces outside of those already provided by the App Builder. ### Entando Kubernetes Controllers -There are a number of controllers that are available to the Entando operator to manage installations and -components in an Entando Cluster. Those controllers are small and lightweight images that are executed as -run to completion pods to manage the installation flow for different parts of the infrastructure. The -controllers are implemented using Quarkus. For more information on the controllers, the Entando custom -resources, and configuring your Entando deployment see also: +There are a number of controllers that are available to the Entando Operator to manage installations and +components in an Entando cluster. These are small and lightweight images that execute as +run-to-completion pods, managing the installation flow for different parts of the infrastructure. The +controllers are implemented using Quarkus. For more information on the controllers, Entando custom +resources, and configuring your Entando deployment, see also: [Custom Resources](../consume/custom-resources.md). GitHub: diff --git a/vuepress/docs/v7.0/docs/curate/ecr-troubleshooting-guide.md b/vuepress/docs/v7.0/docs/curate/ecr-troubleshooting-guide.md index d88d598461..5b1d147177 100644 --- a/vuepress/docs/v7.0/docs/curate/ecr-troubleshooting-guide.md +++ b/vuepress/docs/v7.0/docs/curate/ecr-troubleshooting-guide.md @@ -1,38 +1,36 @@ # Troubleshooting ECR -## A bundle installation/removal has failed, how to access the logs? +## How do I access the logs? +**A bundle installation or removal has failed. How do I access the logs?** -### Overview +Currently the Entando Component Manager logs are only available in Kubernetes through Openshift dashboards or CLI tools like K9s and kubectl. -Currently the Entando component manager logs are available in kubernetes via dashboard (openshift) or cli tools (k9s or kubectl). -If in you Entando cluster you have more than one Entando App custom resource, you will need to know what's the correct component-manager to check using the corresponding Entando App name and namespace where the app has been deployed. ### Solution - -Using `kubectl` and assuming for simplicity that you have only one Entando App named `quickstart` and your Entando cluster is only composed of one namespace, also named `quickstart`, -you can get the component-manager logs using the command +If your Entando cluster has more than one Entando App custom resource, find the component manager in question using the Entando App name and namespace where the app has been deployed. Assuming you have a single Entando App named `quickstart` and your cluster namespace is called `YOUR-NAMESPACE`, +retrieve the component manager logs using this command: ``` -kubectl logs -f deployment/quickstart-server-deployment --namespace quickstart -c de-container +kubectl logs -f deployment/quickstart-server-deployment --namespace YOUR-NAMESPACE -c de-container ``` -**Note**: the `-f` flag is optional and could be used to follow the logs for debugging purposes +Note the `-f` flag is optional and used to follow the logs for debugging purposes. -## My bundle has an issue, how should I publish a new version of the bundle? +## How do I publish a new version +**My bundle has an issue. How do I publish a new version of the bundle?** -### Overview -Sometimes a bundle could have some issues: typos in the `descriptor.yaml` file, wrong references of components or to not available docker images are just a few of the possible errors. +Sometimes a bundle could have issues such as typos in the descriptor.yaml, faulty references for components, or unavailable Docker images. After making the corrections, your bundle will need to be updated. ### Solution -1. If the bundle is shared using a git repository, you can make the required changes to your project and publish the new version to git and generate a new tag for it. -2. Once the new tag is published, update the bundle costum-resource avaialble in you Entando Cluster by adding the new tag to the `tags` objects and replacing the latest `dist-tags` to point to this new version. -3. Proceed with the new installation +1. If the bundle is shared in a Git repository, you can make the required changes to your project, publish the new version to Git, and generate a new tag for it. +2. Once the new tag is published, update the bundle custom resource in the cluster by adding the new tag to the `tags` object and replacing the latest `dist-tags` to point to the new version. +3. Then proceed with the new installation. -If you're actively working on your bundle and you simply want to verify things are working correctly, instead of generating a new tag for each release of the bundle you can try to keep overriding a specific tag using the git command `git tag -f`. We suggest you to follow this practice only during development and not in production. +Note: If you're actively working on your bundle and simply want to verify that things are working correctly, you can override a specific tag using the Git command `git tag -f` instead of generating a new tag for each release of the bundle. You should follow this practice only during development, never in production. -## Bundle installation fails because a file has not been found in the bundle +## ERROR - File not found in bundle +**Installation fails because a file has not been found in the bundle** -### Overview -When a component that is referenced in the `descriptor.yaml` is missing in the bundle or not correctly referenced, the bundle installation fails and in the logs is reported which file has not been found. +When a component that is referenced in the descriptor.yaml is missing in the bundle or not properly called, the bundle installation will fail and the error reported in the logs. ``` ERROR - File with name {filename} not found in the bundle @@ -40,31 +38,27 @@ ERROR - File with name {filename} not found in the bundle ### Solution -When such a problem happens, verify that the component referenced in the descriptor file are actually present in the bundle and that the reference is properly typed. +Verify that the component named in the descriptor file is actually present in the bundle, in the location specified, and that the reference is properly formatted. -Publish a new version of your bundle as described in the -["My bundle has an issue"](#my-bundle-has-an-issue-how-should-i-publish-a-new-version-of-the-bundle) section +Then +[publish a new bundle version](#how-do-i-publish-a-new-version) as explained above. -## Bundle installation failed due to plugin(s) images not reachable +## My plugin Docker image is unreachable +**Bundle installation fails due to plugin images that are not reachable** -### Overview -Plugin included in a bundle are referenced using their docker image. Sometime the image is not available - maybe has not yet be published or is in a private docker registry - and plugin installation can't happen and the entire bundle installation process can't finish successfully +A bundle installation does not complete successfully because a plugin in a bundle, defined by a Docker image, is not available. ### Solution +This may happen if the Docker image for the plugin is located in a private registry or not yet published. Verify that the Docker image you are referencing is published, correctly formatted, and publicly available. -Verify that the docker image you are referencing is correct and publicly available. - -["My bundle has an issue"](#my-bundle-has-an-issue-how-should-i-publish-a-new-version-of-the-bundle) section - -## I can't uninstall a bundle because some components are in use +Then +[publish a new bundle version](#how-do-i-publish-a-new-version) as explained above. -### Overview +## How do I uninstall a bundle +**I can't uninstall a bundle because some components are in use** -When removing an installed bundle, the Entando component manager verfies that the bundle components -are not in use by any other component. Removing such components would cause an error during removal -as in certain case the deleting a component in use is not permitted. +When uninstalling an installed bundle, the Entando Component Manager verfies that the bundle components are not in use by any other component. An error message informs you and does not allow the removal. ### Solution -In order to prevent such errors, the user is alerted and required to manually decouple the bundle -components before beign able to completely remove the bundle from the system. +A bundle cannot be uninstalled if any of its components are in use. To uninstall the bundle, the user must manually remove all references to it and all its component. \ No newline at end of file diff --git a/vuepress/docs/v7.0/docs/reference/deployment-structure.md b/vuepress/docs/v7.0/docs/reference/deployment-structure.md index b7ff010464..cf039913a7 100644 --- a/vuepress/docs/v7.0/docs/reference/deployment-structure.md +++ b/vuepress/docs/v7.0/docs/reference/deployment-structure.md @@ -4,156 +4,130 @@ sidebarDepth: 2 # Entando Deployment Structure -This page provides a high level overview of the key Entando GitHub repositories along with a brief description -of how those repositories are realized in a running Entando deployment. The descriptions provided here are meant -as a guide for identifying opportunities to dig deeper into the architecture and how things are structured -rather than a panacea for understanding the architecture. +This page provides an overview of the key Entando GitHub repositories with brief descriptions +of how these repositories are realized in a running Entando deployment. It also explores the architecture behind the Entando Platform and how its functions are structured. ## entando-operator -The Entando operator coordinates the installation and configuration of all of the components of an Entando -Cluster. The operator can be installed once per Entando Cluster and used to coordinate the plugin lifecycle for -multiple Entando applications across many namespaces. +The Entando Operator coordinates the installation and configuration of all the components in an Entando +cluster. The operator can be installed once per cluster and is used to coordinate the plugin lifecycle for multiple Entando Applications across many namespaces. * GitHub: * DockerHub: #### Customization -It is unlikely that the operator will be customized as part of an Entando implementation. It is not built to -be extended inside the codebase. The most common pattern will be to use the existing custom resources that the -operator knows how to deploy to extend the Entando platform. +Use existing [Entando Custom Resources](../consume/custom-resources.md) to extend the Entando Platform. -## database init containers -During installation, an Entando application needs to create several databases and initialize those -databases with information when deploying from a backup in your images. At initialization, the _entando-k8s-dbjob_ -will be run 5 times in total. Once for keycloak, twice for the entando application (port and serv dbs), once to -populate the Entando application database, and once to create the Component Repository database. +## Database Init Containers +During installation, an Entando Application needs to create and initialize several databases when deploying from a backup of your images. * GitHub: * DockerHub: -The screenshot below highlights the init containers for the Entando application schema creation, db -initialization, and component repository database. +The screenshot below highlights the init containers for the Entando Application schema creation, DB initialization, and component repository database. ![Init Containers Screenshot](./img/init-containers-screenshot.png) -Many managed kubernetes instances like OpenShift won’t show init containers in their dashboards. So if you’re -troubleshooting you may need to look deeper. When fetching logs for an init container using kubectl, you must -pass the container name as an argument to the call. For example, +Many managed Kubernetes instances like OpenShift don’t display init containers on their dashboards. If you’re troubleshooting, the logs may provide some useful information. To fetch logs for an init container using kubectl, you must +pass the container name as an argument. - kubectl logs -c -n +For example: + + kubectl logs YOUR-POD -c YOUR-CONTAINER-NAME -n YOUR-NAMESPACE kubectl logs default-sso-in-namespace-deployment-db-preparation-job-ddbdbddb-a -c default-sso-in-namespace-deployment-db-schema-creation-job -n sprint1-rc #### Customization -It is unlikely that the init containers will be customized as part of an Entando project. The init containers -will automatically restore a backup included in your application so that you can create custom images that -include your application setup. -See [Backing Up and Restoring Your Environment](../../tutorials/devops/backing-up-and-restoring-your-environment.md). +The init containers automatically restore a backup included in your application so that you can create custom images with your application setup. +See [Backing Up and Restoring Your Environment](../../tutorials/devops/backing-up-and-restoring-your-environment.md) for more details. ## entando-de-app -The _entando-de-app_ is a J2EE application and is an instance of the _entando-core_ (see a description of the -_entando-core_ repo below). Reviewing the dependencies of this application in the pom.xml will reveal the -dependencies on the _entando-core_, _entando-engine_, and _admin-console_ which encompass the core -functionality in versions of Entando prior to Entando 6. In a quickstart deployment the _entando-de-app_ is deployed as part of the _entando-composite-app_ multi -container pod. +The **entando-de-app** is a J2EE application and an instance of the [**entando-core**](#entando-core). It provides pathways for other Entando Components and the server image the Entando Operator requires to manage the deployment. The pom.xml for the application reveals its dependencies. + * GitHub: * DockerHub: , #### Customization -The _entando-de-app_ is very likely to be customized as part of an Entando implementation. This image can be -customized with new APIs, legacy Entando plugins, new database tables, or other extensions to the _entando-core_. -It is highly recommended that most extensions to the platform on Entando occur in microservices. However, legacy -integrations, extensions to the CMS, and migrations from earlier Entando versions may require changes to the _entando-de-app_. - -## app-builder -The _app-builder_ is the front end of the _entando-de-app_. It communicates with the _entando-de-app_ via [REST -APIs](../consume/entando-apis.md). The _app-builder_ is a React JS application and is served via node in the default -deployment. In a quickstart deployment, the _app-builder_ container is deployed in the _entando-app_ -multiple container pod. The _app-builder_ also communicates with the Component Manager via REST API to fetch -information about Entando bundles deployed to the Entando Component Repository (ECR). +The **entando-de-app** is very likely to be customized as part of an Entando implementation. +A customized image can include: +* New APIs +* Legacy Entando plugins +* New database tables +* Other extensions to the **entando-core** + +It is recommended that most extensions to the Entando Platform occur in microservices. However, legacy +integrations, extensions to the CMS, and migrations from earlier Entando versions may require changes to the **entando-de-app**. + +## App Builder +The App Builder is the user-friendly frontend UI for the **entando-de-app**. A ReactJS application, it is served via node in the default deployment. In a quickstart deployment, the App Builder container is deployed in the **entando-app** multi-container pod. It communicates with the **entando-de-app** and the Entando Component Manager (ECM) via [REST +APIs](../consume/entando-apis.md). The ECM provides information about bundles deployed to the Entando Component Repository (ECR). * GitHub: * DockerHub: #### Customization -The _app-builder_ is customized as part of many Entando implementations. +The App Builder is customized as part of many Entando implementations. It can be customized at runtime via micro frontends [widget configuration](../../tutorials/create/mfe/widget-configuration.md). -## component-manager(cm) -The _component-manager_ provides the link between the entando-de-app (or your custom core instance) and the ECR. The _component-manager_ queries the entando-k8s service to fetch available -bundles that have been deployed as custom resources inside of an Entando cluster. -The _component-manager_ also manages the relationships between an Entando application and the -installed plugins. This can be seen in the plugin link custom resources in Kubernetes. +## Entando Component Manager (ECM) +The ECM provides the link between the **entando-de-app**, or your custom core instance, and the ECR. The ECM queries the Entando Kubernetes service to fetch available +bundles that have been deployed as custom resources inside the cluster. + +The ECM also manages relationships between an Entando Application and the +installed plugins. This can be seen in the plugin link custom resource in Kubernetes. * GitHub: * DockerHub: -#### Customization -It is unlikely that the _component-manager_ will be customized as part of an Entando implementation. - ## entando-k8s-service -The _entando-k8s-service_ acts as an abstraction layer to fetch data from kubernetes APIs. The primary -functionality is in discovering and making available for installation Entando plugins. The -_entando-k8s-service_ is invoked by the _component-manager_. +The **entando-k8s-service** acts as an abstraction layer to fetch data from Kubernetes APIs. Its primary +function is to discover and make available Entando plugins for installation. The +**entando-k8s-service** is invoked by the ECM. * GitHub: * DockerHub: -#### Customization -It is very unlikely that the _entando-k8s-service_ will be customized as part of an Entando implementation. - -## keycloak -The _entando-keycloak_ project is an extension of the base Keycloak images. The extension provides the default -themes for Entando, a customized realm and clients, and adds the Oracle ojdbc jars for connection to Oracle -databases. +## Keycloak +The **entando-keycloak** project is an extension of the base Keycloak images. It provides default themes for Entando, a customized realm and clients, and Oracle JDBC JARs for connecting to Oracle databases. * GitHub: * DockerHub: #### Customization -The keycloak image will often be customized as part of an Entando implementation. Common extensions will -include changing the theme, adding default connections, adding default social logins, adding default clients, -or other changes. +The Keycloak image can be customized as part of an Entando implementation. Some common extensions are: +* Change the theme +* Add default connections +* Add default social logins +* Add default clients ## Other Key Repositories ### entando-core -The entando-core project is a J2EE application that exposes APIs for the Entando CMS, includes the legacy -admin console, and includes the portal-ui project that performs the server side composition for pages -rendered via an Entando application. Note that only the composition is performed server side. -Javascript code is rendered on the client. The entando-core is realized via an instance that includes the -WAR files generated from a core build as dependencies. In a default deployment this is the _entando-de-app_. +The **entando-core** project is a J2EE application that exposes APIs for the Entando CMS, including the admin console and the portal UI project that performs the server side composition for pages rendered via an Entando Application. Note that only the composition is performed server side. JavaScript code is rendered client-side. The **entando-core** is realized via an instance that includes the +WAR files generated from a core build as dependencies. In a default deployment, this is the **entando-de-app**. * GitHub: * DockerHub: None (deployed to maven central) #### Customization -For users familiar with versions prior to Entando 6, there will be cases where the _entando-core_ is customized. -In most cases, these customizations will be delivered via a WAR overlay in the instance project. +For users familiar with versions prior to Entando 6, there will be cases where the **entando-core** is customized. +Often, these customizations will be delivered via a WAR overlay in the instance project. Using a WAR overlay is a functional approach for users already familiar with the process, but it is highly recommended to extend the platform using microservices for new projects. ### entando-cms -The _entando-cms_ project is the _app-builder_ (React JS) side of the Entando WCMS. It is bundled into the -_app-builder_ at build time and will be included in the default deployment of the _app-builder_ in almost all cases. +The **entando-cms** project is the App Builder (ReactJS) side of the Entando WCMS. It is bundled into the +App Builder at build time and is included in the default deployment of the App Builder in most cases. * GitHub: * DockerHub: None (deployed to npm) #### Customization -In some cases the _entando-cms_ may be customized if new custom features are added to CMS specific -functionality. However, most cases will use the more general _app-builder_ extension points noted above. -The _entando-cms_ does not expose any dedicated extension interfaces outside of those already provided by the -_app-builder_. - -### entando-components -The entando-components project is a collection of legacy plugins for Entando 5 and earlier. These plugins are deployed as WAR dependencies in an entando-core instance. -* GitHub: -* DockerHub: None (deployed to maven central) +In some cases, the **entando-cms** may be customized if new custom features are added to CMS-specific +functionality. However, most cases will use the more general App Builder extension points noted above. The **entando-cms** does not expose any dedicated extension interfaces outside of those already provided by the App Builder. ### Entando Kubernetes Controllers -There are a number of controllers that are available to the Entando operator to manage installations and -components in an Entando Cluster. Those controllers are small and lightweight images that are executed as -run to completion pods to manage the installation flow for different parts of the infrastructure. The -controllers are implemented using Quarkus. For more information on the controllers, the Entando custom -resources, and configuring your Entando deployment see also: +There are a number of controllers that are available to the Entando Operator to manage installations and +components in an Entando cluster. These are small and lightweight images that execute as +run-to-completion pods, managing the installation flow for different parts of the infrastructure. The +controllers are implemented using Quarkus. For more information on the controllers, Entando custom +resources, and configuring your Entando deployment, see also: [Custom Resources](../consume/custom-resources.md). GitHub: