Operate OMAG Server Runtime¶

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 Runtime, 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 Runtime¶

To run the OMAG Server Runtime application, execute the command in this format:

java <java options> -jar omag-server-{release}.jar <properties>

or, for example, to start with a minimal sample configuration:

java -jar omag-server-*.jar --omag.server-config-file=classpath:samples/metadata-repository-server.yml --server.port=9080 --server.ssl.enabled=false

 Project Egeria - Open Metadata and Governance
    ____   __  ___ ___    ______   _____
   / __ \ /  |/  //   |  / ____/  / ___/ ___   ____ _   __ ___   ____
  / / / // /|_/ // /| | / / __    \__ \ / _ \ / __/| | / // _ \ / __/
 / /_/ // /  / // ___ |/ /_/ /   ___/ //  __// /   | |/ //  __// /
 \____//_/  /_//_/  |_|\____/   /____/ \___//_/    |___/ \___//_/

 :: Powered by Spring Boot (v3.1.1) ::

2023-09-19T15:10:45.763+02:00  INFO 94379 --- [           main] o.o.o.s.springboot.OMAGServer            : Starting OMAGServer using Java 17.0.8.1 with PID 94379 (omag-server-platform-5.0.jar started by ***** in /server)
2023-09-19T15:10:45.765+02:00  INFO 94379 --- [           main] o.o.o.s.springboot.OMAGServer            : No active profile set, falling back to 1 default profile: "default"
2023-09-19T15:10:47.488+02:00  INFO 94379 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 9080 (http)
2023-09-19T15:10:47.497+02:00  INFO 94379 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2023-09-19T15:10:47.497+02:00  INFO 94379 --- [           main] o.apache.catalina.core.StandardEngine    : Starting Servlet engine: [Apache Tomcat/10.1.10]
2023-09-19T15:10:47.565+02:00  INFO 94379 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2023-09-19T15:10:47.566+02:00  INFO 94379 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1756 ms
2023-09-19T15:10:48.356+02:00  INFO 94379 --- [           main] EnvironmentConfiguration$$SpringCGLIB$$0 : SSL configuration started working directory: /server
2023-09-19T15:10:48.824+02:00  INFO 94379 --- [           main] o.s.b.a.e.web.EndpointLinksResolver      : Exposing 2 endpoint(s) beneath base path '/actuator'
2023-09-19T15:10:48.895+02:00  INFO 94379 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 9080 (http) with context path ''
2023-09-19T15:10:48.909+02:00  INFO 94379 --- [           main] o.o.o.s.springboot.OMAGServer            : Started OMAGServer in 3.58 seconds (process running for 4.092)
2023-09-19T15:10:48.932+02:00  INFO 94379 --- [           main] o.o.o.s.s.config.OMAGConfigHelper        : Using configuration from class path resource [samples/metadata-repository-server.yml]
2023-09-19T15:10:49.162+02:00  INFO 94379 --- [           main] o.o.o.s.springboot.OMAGServer            : Sending activation request for server: cocoMDS1 and user: OMAGServer
2023-09-19T15:10:49.341+02:00  INFO 94379 --- [           main] o.o.o.s.springboot.OMAGServer            : Activation succeeded for server: cocoMDS1

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 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.

Spring application external config

If you want to know more about how external configuration works, you can read more about it in the Spring Boot Core Features .

OMAG Server Runtime already has default application.properties packaged within the jar distribution. These properties can always be overridden if provided externally to the application.

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 that defines all subsystems and their connectors. It should be valid Configuration Document Structure. Can be written in .json or .yaml file format.	See samples

Creating configuration document

The configuration document can be created by hand if you have a good understanding of 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 to configure different types of servers. Finally, you can retrieve the valid document created for use with the OMAG Server Runtime.

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 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 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 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¶

The default Spring Boot application logging feature is used as the technical logging implementation. Egeria Audit Logs framework 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¶

Application availability state is managed in a standard way using Actuator leveraging the standard internal Spring application lifecycle and its states.

Health state is exposed via management configuration as rest endpoints, which can be used as probes to manage pod lifecycle in Kubernetes.

Example using standard actuator endpoints to retrieve health information:

> curl http://localhost:9080/actuator/health/livenessState 
{"status":"UP"} 

> curl http://localhost:9080/actuator/health/readinessState
{"status":"UP"}

Default logging and monitoring configuration¶

Already configured with default application.properties

logging.level.org.odpi.openmetadata=error
logging.level.org.odpi.openmetadata.frameworks.auditlog=info
logging.level.org.odpi.openmetadata.serverchassis.springboot=info

management.health.defaults.enabled=false
management.health.livenessstate.enabled=true
management.health.readinessstate.enabled=true

management.endpoints.enabled-by-default=false
management.endpoint.health.enabled=true
management.endpoint.health.show-details=always
management.endpoint.metrics.enabled=true
management.endpoints.web.exposure.include=metrics,health

For more information on customising common application properties, see the Spring Reference Documentation.

Running in a container¶

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 .

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 and reuse the image configured by default to initialise the OMAG server platform.

All other settings can be configured by setting the environment variables that configure the OMAG server behaviour.

Running in Docker¶

To run OMAG Server as a metadata repository using the sample configuration, run the following command:

docker run --name omag-server -p 9443:9443 --env JAVA_APP_JAR="/deployments/server/omag-server-5.0.jar" --env LOADER_PATH="/deployments/server/lib" --env OMAG_SERVERCONFIGFILE="classpath:samples/metadata-repository-server.json" quay.io/odpi/egeria:5.0

Run in Kubernetes¶

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 egeria-server Helm chart. It can be used as a quick reference for defining Kubernetes deployment and configuration resources, and for planning more complex deployments.