Recipe 2: Auto-starting with a simple OMAG server
In Recipe 1, we successfully started up the Egeria OMAG server platform from the command line - but left it un-configured and hence unable to do anything useful yet. So in this recipe we are going to take advantage of one of the simple pre-canned configurations that Egeria ships with. We will do this in three simple steps:
Inspect what we have already.
Use a sample configuration and set up the platform to automatically start with it....
Investigate the running configuration.
Ok, simple enough - let's go.
Some Basics
In Recipe 1, we reviewed a bit of the distribution structure of Egeria. In this recipe, we are going to make use of some of the accelerators that Egeria provides. The first is the egeria-platform-report which is a small but useful java application that reports on the current configuration of a running OMAG server platform. The second, are some of the pre-built configurations that we can use to start up an Egeria platform. We will use the simplest one, appropriately named simple-metadata-store. After we restart the Egeria platform with the simple-metadata-store we will re-run the egeria-platform-report and see what's changed.
As we will discover, this configuration is about as basic as we can get. It uses an in-memory metadata repository and can't communicate with other servers. But it does provide access to a wealth of Egeria services (often called open access services) that we can experiment with. And we will ...
1. Let's inspect
This recipe builds on the first, so hopefully, you've already completed the first. If not, please go to https://pdr-associates.com/blog/recipe1 and do so. To recap, in recipe 1, I created a directory called egeria_sandbox, downloaded and uncompressed the Egeria distribution file, and ran Egeria from the command line. OK - so now lets go back to that same directory and continue.
Looking around
As you may recall from recipe 1, if we look at the root directory of the Egeria distribution we see the following structure:
If we change directory (again, remember that I put my distribution into egeria_sandbox - you may have chosen something else) to egeria_sandbox/egeria-platform-4.3-sandbox.gz/assembly/etc/reports then you will see a java program called egeria-platform-report.jar. This handy little utility will create a report describing the configuration of a running Egeria platform. Let's give it a whirl.
Oops...did I break something?
Go ahead and execute egeria-platform-report by typing in your command window:
If you aren't still running Egeria, this command will come back with a wonderfully descriptive error message:
So - what's going on? The short answer is that we are being told that the Egeria platform isn't running (at least not on https://localhost:9443). But its worth spending a moment to read through the message more completely. We'll cover this in more detail in a subsequent recipe, but as is often the case when reading error messages and tracebacks, it is useful to start at the end and work towards the front. In this case, the last statement is Connection refused - which is a pretty big hint that either the Egeria platform isn't running (at least where we were looking) or that there is a more fundamental communications error. In our case, we are being told - consider starting the Egeria platform. So let's do that and try again.
Let's try again
At this point it's useful to start another terminal window or open a new tab to get another shell going. In this new window, change directory to where the Egeria platform jar file is and start it (strictly speaking we don't have to start it from the same directory, but it is simpler since Java picks up useful defaults that would otherwise need to be specified). If you are in the reports directory then we:
and if we list the directory we see omag-server-platform-4.3.jar. Run it with:
We should see output similar to what we saw at the end of recipe 1.
Good. Now lets switch back to our other terminal window and try again.
This time we should see some much more interesting output - in fact, so much that it might scroll off the screen. But that's ok, this handy little utility automatically creates a markdown formatted output file called egeria-platform-report.md that we can open with our favorite markdown reader (or just look at the contents with any text editor). Here is a copy of the output that I see:
From the output we can quickly observe two things - first, Egeria has a very rich set of available services ranging from cataloging all sorts of digital assets to glossaries and governance; and second, there are no servers deployed on the platform to provide these services. Basically, we have an empty platform that has the potential to provide tremendous capabilities - but we haven't asked it to...yet.
2. Start the Egeria OMAG Server Platform with a pre-configured OMAG Server
So now lets re-deploy Egeria with a pre-built server configuration that can provide some of these capabilities. Egeria is exceptionally flexible, and can be configured to support many different goals and requirements. The OMAG server we are about to configure is aptly named simple-catalog-store - because it is just that.
One of the nice features packed into Egeria is the ability to automatically start servers when it first comes up. We can make use of this facility by either passing a parameter on the command line or by updating the application.properties file with the same information. For more details, see: Configuring the OMAG Server Platform.
Let's edit the application.properties file. This file, which is a standard Spring Boot configuration file, holds a wealth of parameters that you may be interested in changing - but not just yet. So here goes:
If Egeria is still running from your command line, you can stop it with
control-c.Open the
application.propertiesfile with your favorite text editor or IDE.Find the line:
startup.server.list= and edit it to say
Now startup the Egeria platform as we have before:
Now if you look at the terminal window, you'll see a lot more output as Egeria starts and configures the server named simple-metadata-store. The output should indicate a lot of different services starting up - and if it didn't...if it gave you an error that ends with something like:
There is probably a typo in the server name - look carefully at the error message as it tells you what it found as the name of the OMAG server to start.
3. Investigate the running configuration
Ok - so now that we have the Egeria OMAG Server Platform running with an OMAG server named simple-metadata-store running in a terminal window, let's go see how its configured by re-running the egeria-platform-report program to see what it tells us.
(Re)Open a terminal window and get to the directory where the reporting utility was - in my case it is at egeria_sandbox/egeria-platform-4.3-sandbox.gz/assembly/etc/reports.
As you recall, our reporting utility outputs a file that by default is named
egeria-platform-report.md. If you have this in your directory then go ahead either rename or delete it so that we can create a fresh new one (if you don't, the reporting utility will append the results of the new execution to the same file - which could also be interesting). Run the report with:
This should produce a new (or updated)
egeria-platform-report.mdfile. If we review the contents we would see a lot more sections filled out than we saw previously. Sections in the report tell us: a. The address of the platform: https://localhost:9443 b. The servers running on the platform - we only have one server currently running: simple-metadata-store which is a type of OMAG server called a Metadata Access Store meaning that it is a server with a local metadata repository that provides OMAG services. The server is configured with a native repository connector (one that supports all the Egeria open metadata types) and in this case, the repository is configured to use the InMemoryOMRSRepositoryConnectorProvider There are many other repository options to choose from - for more details see connector catalog. c. The report tells us the last time the server was started and its current status. d. The simple-metatadata-store server is currently running about 28 services (if my count is correct). Each service offers a specific set of capabilities such as viewing a glossary or supporting an asset owner. A server can be dynamically configured to provide the services required. A full list of available services can be found at Egeria services. e. We can also see that there are two other configured servers on the platform - but they aren't running. See if you can find them in the report. Hint: they are called active-metadata-store and integration-daemon. We could start or auto-start these servers - but they are configured to exchange information using Kafka which we haven't set up yet.
Recap
The platform report shows us all the known information about an OMAG Server Platform. Many OMAG servers, of different types can be run on the platform concurrently. The configuration for a server can be pre-built and can be updated during runtime. A server (and its configuration) can also be created during runtime (once the platform is started). Pre-configured servers can be automatically started when the platform starts. Each of these servers is independently configured to establish what it can do and how it does it. All configuration is dynamic - we can send requests to the OMAG Server Platform or to individual Servers on the platform that alter their configuration. Egeria provides a flexible and dynamic environment that can be tuned to the needs of different workloads and communities.
In the next recipe, we will use the cURL command to demonstrate a simple way of interacting with Egeria. Stay tuned.