From aa7d858f2ec0df89b69089b3b5e4291b19f2c4ec Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Thu, 28 Jul 2022 12:30:18 -0700 Subject: [PATCH 1/4] ENDOC-525 --- .../docs/next/docs/getting-started/ent-svc.md | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index b497c4f967..46ecab6278 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -1,3 +1,61 @@ --- sidebarDepth: 1 --- + +# Auxiliary Services + +The following sections discuss auxiliary services and commands. + +## Services + +When the Entando Bundle CLI enables a service, a default auxiliary configuration is generated and stored as a Docker Compose YAML file in the bundle's 'svc' folder. Three services are available out of the box: `mysql`, `postgresql` and `keycloak`. + +- `mysql` and `postgresql` obey the same naming convention + - The username and password are derived from the bundle name, e.g. YOUR-BUNDLE has the username YOUR-BUNDLE-USER and the password YOUR-BUNDLE-PASSWORD + - A database is automatically created and given the bundle name, e.g. YOUR-BUNDLE + +- `keycloak` contains the Entando-related configuration + - The `keycloak` realm name is 'entando-dev' + - The console is accessible at *http://localhost:9080* with username: *admin*, password: *admin* + - All roles and permissions are preset, based on the Keycloak realm-config file + - The `keycloak.yaml`, realm-config and user config files are located in the 'keycloak' folder inside 'svc' + +A custom service can be added to a bundle's 'svc' folder as a Docker Compose YAML file. The file and service must have the same name, e.g. if the service filename is `mysql.yml`, then the service name must be `mysql`: + +``` yaml +version: '3.7' + +services: + # since filename is mysql.yml, service name is 'mysql' as declared below: + mysql: + image: mysql + ... +``` + +## Commands + +Use `ent bundle svc` to enable, disable, start, stop, restart, print the logs of, or list services. Services must be formatted as Docker Compose YAML files in the 'svc' bundle folder. + +To run auxiliary operations, a service must be enabled. Enabled services are listed under the 'svc' attribute of the bundle descriptor, `entando.json`. Common auxiliary service commands are detailed below. + +| Command | Description +| :- | :- +| `ent bundle svc enable ` | Adds the service(s) to the bundle’s auxiliary services +| `ent bundle svc disable ` | Removes the service(s) from the bundle’s auxiliary services +| `ent bundle svc start ` | Starts the enabled service(s) +| `ent bundle svc stop ` | Stops the enabled service(s) +| `ent bundle svc restart ` | Restarts the enabled service(s) +| `ent bundle svc logs ` | Prints the enabled service log(s) +| `ent bundle svc list` | Lists all enabled services + +**Command details:** + +- `svc enable`: Adds the service(s) to the 'svc' attribute of the bundle descriptor + +- `svc disable`: Removes the service(s) from the 'svc' attribute of the bundle descriptor + +- `svc logs`: The log of a running service will continue to update until exited via `Ctrl+C` + +- `svc list`: Include the option `--available` to list all services located in the 'svc' bundle folder + +- Auxiliary commands can operate on multiple services by listing each service name as an argument, e.g. `ent bundle svc start service_1 service_2`. The option `--all` applies the command to all enabled bundle services. \ No newline at end of file From 3d5a0fa0d5ccfe25d5908e97d4f307dd9adb327f Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Fri, 29 Jul 2022 15:30:03 -0700 Subject: [PATCH 2/4] ENDOC-525 Minor fixes --- vuepress/docs/next/docs/getting-started/ent-svc.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index 46ecab6278..facad9c8d4 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -14,7 +14,7 @@ When the Entando Bundle CLI enables a service, a default auxiliary configuration - The username and password are derived from the bundle name, e.g. YOUR-BUNDLE has the username YOUR-BUNDLE-USER and the password YOUR-BUNDLE-PASSWORD - A database is automatically created and given the bundle name, e.g. YOUR-BUNDLE -- `keycloak` contains the Entando-related configuration +- `keycloak` configures authentication for Entando - The `keycloak` realm name is 'entando-dev' - The console is accessible at *http://localhost:9080* with username: *admin*, password: *admin* - All roles and permissions are preset, based on the Keycloak realm-config file @@ -50,10 +50,6 @@ To run auxiliary operations, a service must be enabled. Enabled services are lis **Command details:** -- `svc enable`: Adds the service(s) to the 'svc' attribute of the bundle descriptor - -- `svc disable`: Removes the service(s) from the 'svc' attribute of the bundle descriptor - - `svc logs`: The log of a running service will continue to update until exited via `Ctrl+C` - `svc list`: Include the option `--available` to list all services located in the 'svc' bundle folder From 9e486f152dbd2c324458712ec4ef31bf72716739 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Sat, 30 Jul 2022 19:28:34 -0700 Subject: [PATCH 3/4] ENDOC-525 Introduce aux services --- vuepress/docs/next/docs/getting-started/ent-svc.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index facad9c8d4..a1d07ce2d3 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -4,7 +4,9 @@ sidebarDepth: 1 # Auxiliary Services -The following sections discuss auxiliary services and commands. +Auxiliary services extend the capabilities of a local development environment. Kubernetes can be configured to point to externally managed services, such as MySQL or PostgreSQL, or services are provided by the platform (e.g. Keycloak or RedHat SSO). + +The following sections describe how Entando supports and implements auxiliary services. ## Services From 2ca54cb31474f48109c0e7e412e7648b656c1642 Mon Sep 17 00:00:00 2001 From: Lydia Pedersen Date: Mon, 1 Aug 2022 09:03:21 -0700 Subject: [PATCH 4/4] ENDOC-525 Revise intro --- vuepress/docs/next/docs/getting-started/ent-svc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vuepress/docs/next/docs/getting-started/ent-svc.md b/vuepress/docs/next/docs/getting-started/ent-svc.md index a1d07ce2d3..c7a49ea413 100644 --- a/vuepress/docs/next/docs/getting-started/ent-svc.md +++ b/vuepress/docs/next/docs/getting-started/ent-svc.md @@ -4,7 +4,7 @@ sidebarDepth: 1 # Auxiliary Services -Auxiliary services extend the capabilities of a local development environment. Kubernetes can be configured to point to externally managed services, such as MySQL or PostgreSQL, or services are provided by the platform (e.g. Keycloak or RedHat SSO). +Auxiliary services add capabilities to a local environment to accelerate application development. This is in contrast to developing on Kubernetes, where the equivalent services are either provisioned by the Entando Platform or are externally managed and pointed to by the application. The following sections describe how Entando supports and implements auxiliary services.