Merge pull request #849 from atruvia/main

Fixed some typos and improved readability

site/docs/guides/operations/opearate-omag-server-starter.md → site/docs/guides/operations/operate-omag-server-starter.md

@@ -1,18 +1,18 @@
 # Operate OMAG Server Starter
 
-This guide focuses on providing instructions how to operate server as stand-alone application process. This deployment choice gives you low level control of the application runtime and it requires direct interaction with your IT infrastructure.
+This guide focuses on providing instructions for running the server as standalone application process. This deployment option gives you a low level control over the application runtime and requires direct interaction with your IT infrastructure.
 
-With OMAG Server Starter each server runs in its own dedicated JVM process. All the required parameters to start a server are always determined up-front and supplied as configuration properties to the application. This approach is key to achieve immutable configuration state in case of running containerized deployment.
+With OMAG Server Starter, each server runs in its own dedicated JVM process. All the required parameters required to start a server are always pre-defined and delivered to the application as configuration properties. This approach is key to achieving an immutable configuration state when running containerised deployments.
 
 > Quick jump to installation steps (coming soon)
 
 ## Running OMAG Server Starter
 
-To run the OMAG server starter application you execute command in this format:
+To run the OMAG Server Starter application, execute the command in this format:
 
 `java <java options> -jar omag-server-{release}.jar <properties>`
 
-or for example, to start with minimal sample configuration:
+or, for example, to start with a minimal sample configuration:
 
 ```bash
 java -jar omag-server-*.jar --omag.server-config-file=classpath:samples/metadata-repository-server.yml --server.port=9080 --server.ssl.enabled=false
@@ -45,59 +45,59 @@ java -jar omag-server-*.jar --omag.server-config-file=classpath:samples/metadata
 
 ```
 
-> Note that the java executable jar is different then in case of running OMAG server platform.
+> Note that the Java executable jar is different than when running the OMAG server platform.
 
 ## Configuration Reference
 
-Considering that the starter application is implemented using Spring Boot, we can use different styles to configure the server starter. It is a matter of choice in what way properties will be provided to the application: command line options, application properties or environment variables. The started application will load all and use them on startup.
+Considering that the starter application is implemented using Spring Boot, we can use different styles to configure the server starter. It is a matter of choice how to provide properties to the application: Command line options, application properties or environment variables. The launched application will load them all and use them on startup.
 
 !!! info "Spring application external config"
-    If want to know more about how external configuration works, you can read more int the spring boot [core features](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config){ target=_blank } .
+    If you want to know more about how external configuration works, you can read more about it in the Spring Boot [Core Features](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.external-config){ target=_blank } .
 
-OMAG server starter already has default [`application.properties`](https://github.com/odpi/egeria/blob/main/open-metadata-implementation/server-chassis/server-chassis-spring/src/main/resources/application.properties){ target=gh } packaged within the jar distribution. These properties can ba always overwritten if they are provided to the application externally.
+OMAG Server Starter already has default [`application.properties`](https://github.com/odpi/egeria/blob/main/open-metadata-implementation/server-chassis/server-chassis-spring/src/main/resources/application.properties){ target=gh } packaged within the jar distribution. These properties can always be overridden if provided externally to the application.
 
-Below you can find reference properties that define the application behavior.
+Below are reference properties that define the behaviour of the application.
 
 ### Server Configuration File
 
 | Property name           | Environment variable  | Description  | Example |
 |-------------------------|-----------------------|--------------|---------|
-|`omag.server-config-file`|`OMAG_SERVERCONFIGFILE`| The OMAG server configuration file defining all subsystems and respective connectors. It should be valid [configuration document structure](/concepts/configuration-document/#configuration-document-structure). Can be written in .json or .yaml file format. | See [samples](https://github.com/odpi/egeria/tree/main/open-metadata-implementation/server-chassis/server-chassis-spring/src/main/resources/samples){ target=gh } |
+|`omag.server-config-file`|`OMAG_SERVERCONFIGFILE`| The OMAG server configuration file that defines all subsystems and their connectors. It should be valid [Configuration Document Structure](/concepts/configuration-document/#configuration-document-structure). Can be written in .json or .yaml file format. | See [samples](https://github.com/odpi/egeria/tree/main/open-metadata-implementation/server-chassis/server-chassis-spring/src/main/resources/samples){ target=gh } |
 
 !!! tip "Creating configuration document"
-    The configuration document can be crafted by hand if you understand well [configuration document structure](/concepts/configuration-document/#configuration-document-structure). Safe option is to use OMAG server platform deployment and create configuration document using admin services. Refer to [Admin guide](/guides/admin/servers) to see how different server types are configured. Finally you can [retrieve](/guides/admin/servers/#retrieving-the-configuration) the valid document created for use with the server starter.
+    The configuration document can be created by hand if you have a good understanding of [Configuration Document Structure](/concepts/configuration-document/#configuration-document-structure). A safe option is to use the OMAG server platform deployment and create the configuration document using the admin services. See the [Admin Guide](/guides/admin/servers) to configure different types of servers. Finally, you can [retrieve](/guides/admin/servers/#retrieving-the-configuration) the valid document created for use with the Server Starter.
 
 ### Additional Libraries
 
 | Property name           | Environment variable  | Description  | Example |
 |-------------------------|-----------------------|--------------|---------|
-| `loader.path` | `LOADER_PATH` | The Spring Boot extended class-path. This is the main mechanism used to load externally Egeria or third party connector libraries. | loader.path="/deployments/server/lib" |
+| `loader.path` | `LOADER_PATH` | The Spring Boot extended class path. This is the main mechanism used to load external Egeria or third party connector libraries. | loader.path="/deployments/server/lib" |
 
 ### Web Server and SSL Transport
 
 | Property name           | Environment variable  | Description  | Example |
 |-------------------------|-----------------------|--------------|---------|
 |`server.port` | SERVER_PORT | Server transport port | server.port=9443 |
 |`server.ssl.enabled`| SERVER_SSL_ENABLED | Enables SSL transport for the embedded web server (Tomcat) | server.ssl.enabled=false disables server ssl. In this case all other server.ssl properties are not required. |
-|`server.ssl.key-store`| SERVER_SSL_KEYSTORE | Java key-store file used to load the server certificates | server.ssl.key-store=keystore.p12 |
-|`server.ssl.key-store-password`| SERVER_SSL_KEYSTORE_PASSWORD | Secret used by the server to access the key-store file | server.ssl.key-store-password=egeria |
+|`server.ssl.key-store`| SERVER_SSL_KEYSTORE | Java keystore file used to load server certificates | server.ssl.key-store=keystore.p12 |
+|`server.ssl.key-store-password`| SERVER_SSL_KEYSTORE_PASSWORD | Secret used by the server to access the keystore file | server.ssl.key-store-password=egeria |
 |`server.ssl.keyStoreType` | SERVER_SSL_KEYSTORETYPE | The type of keystore file used | server.ssl.keyStoreType=PKCS12 |
-|`server.ssl.keyAlias`| SERVER_SSL_KEYALIAS | The alias used for the ssl key | server.ssl.keyAlias=egeriaserverchassis |
-|`server.ssl.trust-store` | SERVER_SSL_TRUSTSTORE | Java trust-store file used by the server | server.ssl.trust-store=truststore.p12 |
-|`server.ssl.trust-store-password` | SERVER_SSL_TRUSTSTOREPASSWORD | Secret used by the server to access trust-store file | server.ssl.trust-store-password=egeria |
-|`strict.ssl`| STRICT_SSL | Controls mTLS for http client, thats if ssl should be validated for outbound connections | strict.ssl=false will turn off client ssl validation for external servers (considered unsafe). |
+|`server.ssl.keyAlias`| SERVER_SSL_KEYALIAS | The alias used for the SSL key | server.ssl.keyAlias=egeriaserverchassis |
+|`server.ssl.trust-store` | SERVER_SSL_TRUSTSTORE | Java truststore file used by the server | server.ssl.trust-store=truststore.p12 |
+|`server.ssl.trust-store-password` | SERVER_SSL_TRUSTSTOREPASSWORD | Secret used by the server to access truststore file | server.ssl.trust-store-password=egeria |
+|`strict.ssl`| STRICT_SSL | Controls mTLS for the http client, i.e. whether to validate SSL for outgoing connections. | strict.ssl=false will disable client SSL validation for external servers (considered insecure). |
 
 ### Logging
 
-Default Spring Boot application [logging feature](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.logging){ target=_blank } is used as technical log implementation. Egeria [Audit Logs framework](/frameworks/alf/overview/) can be configured further via SLF4J connector to re-direct the OMAG logs to the technical logging or log directly via console connector (default).
+The default Spring Boot application [logging feature](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.logging){ target=_blank } is used as the technical logging implementation. Egeria [Audit Logs framework](/frameworks/alf/overview/) can be further configured via the SLF4J connector to redirect the OMAG logs to the technical logging or to log directly via the console connector (default).
 
 ### Application availability
 
-The application availability state is managed in a standard way using [Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.spring-application.application-availability){ target=_blank } leveraging standard internal Spring application lifecycle and its states.
+Application availability state is managed in a standard way using [Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/features.html#features.spring-application.application-availability){ target=_blank } leveraging the standard internal Spring application lifecycle and its states.
 
-Health state is exposed via management configuration as rest endpoints that can be used as probes for managing pod lifecycle in Kubernetes.
+Health state is exposed via management configuration as rest endpoints, which can be used as probes to manage pod lifecycle in Kubernetes.
 
-Example using default actuator endpoints to retrieve health information:
+Example using standard actuator endpoints to retrieve health information:
 
 ```bash
 > curl http://localhost:9080/actuator/health/livenessState 
@@ -128,28 +128,28 @@ management.endpoint.metrics.enabled=true
 management.endpoints.web.exposure.include=metrics,health
 ```
 
-More info on customizing common Application Properties can be found in spring [reference documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#appendix.application-properties){ target=_blank }.
+For more information on customising common application properties, see the Spring [Reference Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#appendix.application-properties){ target=_blank }.
 
-## Run in a Container
+## Running in a container
 
-To run the server starter application in a container you need container image. Egeria core image offers variety of options to run Egeria OMAG applications. As part of the official distribution, the full Egeria assembly is packaged as Docker image including the OMAG server started jar. The image is based on RedHat's [ubi9/openjdk-17](https://catalog.redhat.com/software/containers/ubi9/openjdk-17-runtime/61ee7d45384a3eb331996bee){ target=_blank }
+To run the server starter application in a container, you need a container image. The Egeria core image provides a variety of ways to run Egeria OMAG applications. As part of the official distribution, the complete Egeria assembly is packaged as a Docker image, including the OMAG server starter jar. The image is based on RedHat's [ubi9/openjdk-17](https://catalog.redhat.com/software/containers/ubi9/openjdk-17-runtime/61ee7d45384a3eb331996bee){ target=_blank } .
 
-The executable jar is located in the image at following location:
+The executable jar is located in the following location in the image:
 
 `/deployments/server/omag-server-{release}.jar`
 
-By modifying the environment variable `JAVA_APP_JAR` to point to this location, you modify the container entry point thus reusing the image configured by default to initialize OMAG server platform.
+By modifying the environment variable `JAVA_APP_JAR` to point to this location, you modify the container entry point and reuse the image configured by default to initialise the OMAG server platform.
 
-All other settings can be configured by setting the environment variables configuring the OMAG server behavior.
+All other settings can be configured by setting the environment variables that configure the OMAG server behaviour.
 
-### Run in Docker
+### Running in Docker
 
-To run OMAG Server as Metadata Repository using sample configuration execute following command:
+To run OMAG Server as a metadata repository using the sample configuration, run the following command:
 
 ```bash
 docker run --name omag-server -p 9443:9443 --env JAVA_APP_JAR="server/omag-server-4.3.jar" --env LOADER_PATH="/deployments/server/lib" --env OMAG_SERVERCONFIGFILE="classpath:samples/metadata-repository-server.json" quay.io/odpi/egeria:4.3
 ```
 
 ### Run in Kubernetes
 
-To run in a Kubernetes environment, you need to make certain choices and properly plan the deployment resources. To showcase how simple single server deployment can be done we created [`omag-server`](https://github.com/odpi/egeria-charts/tree/main/charts/egeria-server){ target=gh } Helm chart. It can be used as quick reference for defining kubernetes deployment and configuration resources and planning more complex deployments.
+To run in a Kubernetes environment, you need to make certain choices and properly plan the deployment resources. To show how easy a single server deployment can be, we have created a [`omag-server`](https://github.com/odpi/egeria-charts/tree/main/charts/egeria-server){ target=gh } Helm chart. It can be used as a quick reference for defining Kubernetes deployment and configuration resources, and for planning more complex deployments.

site/docs/guides/planning/runtime/overview.md

@@ -23,7 +23,7 @@ It is a simple command to move an OMAG Server from one platform instance to anot
 ![OMAG Server deployment choices](/concepts/egeria-operations-server-choices-no-description.svg)
 
 !!! info "Container platform deployment"
-    Alternatively, for cloud or hybrid deployment scenarios you may want to move some of the platform responsibilities to orchestrated container hosting environment like Kubernetes. In such a scenario, OMAG servers run as individual containers. To visualize this looking at the topology picture at the beginning, the blue rounded boxes are Kubernetes clusters and orange circles are OMAG servers running as containers. Read more about this approach in [Container platform deployment](#container-platform-deployment) section below.
+    Alternatively, for cloud or hybrid deployment scenarios, you may want to offload some of the platform responsibilities to an orchestrated container hosting environment such as Kubernetes. In such a scenario, OMAG servers run as individual containers. To visualise this, look at the topology image at the beginning: The blue rounded boxes are Kubernetes clusters and the orange circles are OMAG servers running as containers. Read more about this approach in the [Container Platform Deployment](#container-platform-deployment) section below.
 
 Different types of technology need different types of integration and Egeria has OMAG Servers to match. Each type of OMAG Server is focused on the integration of a specific type of tool, engine or platform:
 
@@ -93,7 +93,7 @@ Kubernetes (or k8s) is de-facto standard platform for deploying, scaling and man
 
 > It is very important to note that wether you choose to run server on a native OMAG platform or in a stand alone container runtime, the same functional principles apply - all servers are interoperable and comply to the open metadata exchange protocols.
 
-## More detail to follow...
+## More detail to follow
 
 The text above is a very high level overview of the planning process. More detail will be added to this guide as time permits.
 

site/mkdocs.yml

@@ -141,7 +141,7 @@ nav:
           - Migration: guides/migration/migrating-configuration-documents.md
       - Operations:
           - Operate OMAG Server Platform: guides/operations/overview.md
-          - Operate OMAG Server Starter: guides/operations/opearate-omag-server-starter.md
+          - Operate OMAG Server Starter: guides/operations/operate-omag-server-starter.md
           - Egeria in Kubernetes:
               - Egeria in Kubernetes: guides/operations/kubernetes/index.md
               - Introduction to Kubernetes: guides/operations/kubernetes/k8s.md