Docker tutorial¶
Docker is a simple container runtime and standard.
Every time the egeria Pull Request (PR) build runs, it creates a latest docker image of egeria based on the latest content of the main branch of egeria.git and pushes it to the docker catalog on the Docker website. The site also contains docker images for each official release of egeria.
Alternatively, you can build a customized docker image of egeria, that includes or excludes the connectors and services that you need.
This page takes you through the different options for building and running egeria using docker containers.
Building your own docker image¶
Building a customized docker image¶
The top-level directory of the Egeria omag-server-platform assembly contains the following files:
$ ls
Dockerfile LICENSE NOTICE README.md assembly dist
The Dockerfile contains the properties for building a docker image of all the files under assembly/platform.
Once you have the contents of assembly/platform as you want them, run the docker command:
docker build -t egeria-platform:{myversion} -f Dockerfile .
{myversion} with a tag name for this docker image. The example below used latest as the tag name.
? docker build -t egeria-platform:latest -f Dockerfile .
[+] Building 44.9s (5/5) FINISHED docker:desktop-linux
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 3.28kB 0.0s
=> [internal] load .dockerignore 0.0s
=> => transferring context: 2B 0.0s
=> [internal] load metadata for registry.access.redhat.com/ubi9/openjdk-17:latest 1.5s
=> [1/1] FROM registry.access.redhat.com/ubi9/openjdk-17@sha256:3eded7b50a5ff8a55895c7b70c9dfc6e320363e5812a68747f281f8f4bb323ac 43.3s
=> => resolve registry.access.redhat.com/ubi9/openjdk-17@sha256:3eded7b50a5ff8a55895c7b70c9dfc6e320363e5812a68747f281f8f4bb323ac 0.0s
=> => sha256:5cbda490fcb7ab72e85cfba7098858cd3ed6bb15f95687e86979f6d4ac7b2f15 596B / 596B 0.0s
=> => sha256:5b5deb1288720666a590472d9a506500df9ebe3c817e9710327162ccd24c4e22 24.19kB / 24.19kB 0.0s
=> => sha256:62742f27dce5ebff467a57ad6bfa680820f3bc534cc313627f8113246276bf0f 37.83MB / 37.83MB 17.9s
=> => sha256:f008a4f4b21c818e8bbd4e2521eb30ab0f8a43dc259e9e51c0d134641e343acd 110.80MB / 110.80MB 37.5s
=> => sha256:3eded7b50a5ff8a55895c7b70c9dfc6e320363e5812a68747f281f8f4bb323ac 1.47kB / 1.47kB 0.0s
=> => extracting sha256:62742f27dce5ebff467a57ad6bfa680820f3bc534cc313627f8113246276bf0f 2.0s
=> => extracting sha256:f008a4f4b21c818e8bbd4e2521eb30ab0f8a43dc259e9e51c0d134641e343acd 5.5s
=> exporting to image 0.0s
=> => exporting layers 0.0s
=> => writing image sha256:5a2c784ed7558dc625d109c04c8b5e78534b270a29d3011eb771fd01724c097f 0.0s
=> => naming to docker.io/library/egeria-platform:latest 0.0s
What's Next?
View summary of image vulnerabilities and recommendations → docker scout quickview
The resulting docker image is published to the docker service configured on your local machine.
Using the standard docker container on docker hub¶
This docker image provides a simple way to bring a runnable version of Egeria onto your machine. It also provides the basis for a Kubernetes deployment of Egeria.
The docker catalog page for egeria is at https://hub.docker.com/r/odpi/egeria. The Overview tab describes the docker container.
The Tags tab shows the different releases that are available.
Getting the docker runtime¶
The docker image needs a runtime to execute. It can run in the cloud using Docker Hub or on your machine using the Docker Desktop. The description below describes how to use the docker desktop.
Docker Desktop supports running a docker image as a standalone container, or as part of group of containers started with docker-compose.
Go to the Docker website and select the Download Docker Desktop.
Follow the instructions for you operating system. For macOS, the docker desktop is installed like a standard application.
Once it is installed, it can be launched like any application, such as through the launchpad/start menu.
This tutorial explains how to use the Egeria Docker Image published to the docker catalog at https://hub.docker.com/r/odpi/egeria.
Egeria's docker image includes the Egeria install image. When the image is started using docker, a new egeria docker container is created. As it starts up, an instance of the Egeria runtime - that is the OMAG Server Platform - is started at port https 9443.
This container can be incorporated into larger container orchestration environments or used standalone.
This tutorial describes how to use it standalone. The Open Metadata Labs
use this container with Kubernetes
container services to create a complete open metadata solution.
Link to Open Metadata Labs to learn more.
Working with Egeria's docker image¶
Once the docker desktop is installed, start the docker desktop application. It may take a little while to complete its start up so check it is running before continuing.
For example, on macOS, the docker desktop can be found on the Launchpad. Once it is running, the docker whale icon appears on the top menu bar. Clicking on the docker whale icon reveals a menu and the status of the desk top is visible. This menu is used to shut down docker at the end of the dojo.
Downloading the egeria docker image¶
The command to download Egeria's docker image is docker pull odpi/egeria.
This is issued from a command/terminal window in the directory where you want the
container to be copied to.
If you see the following response, then the docker runtime is not installed properly on your machine.
$ docker pull odpi/egeria
-bash: docker: command not found
If all is well, the image downloads. Notice it is pulling the latest main build by default.
$ docker pull odpi/egeria
Using default tag: latest
latest: Pulling from odpi/egeria
e7c96db7181b: Pull complete
f910a506b6cb: Pull complete
b6abafe80f63: Pull complete
a83b87485b54: Pull complete
10d9ee7d5688: Pull complete
9558171b7a95: Pull complete
Digest: sha256:18451a4676a6688e03f284f887ba5be7026c17805ee0b919ed02cb131621d45b
Status: Downloaded newer image for odpi/egeria:latest
docker.io/odpi/egeria:latest
$
docker run --publish 19443:9443 odpi/egeria.
This will start the image as a new docker container. As the container initializes it starts a single copy of the
OMAG Server Platform.
The OMAG Server Platform is the Egeria runtime platform where the Egeria REST services run.
The --publish 19443:9443 parameter maps the 9443 port inside the docker that the OMAG Server Platform
has registered with to port 19443
You should see the server logo come up and finally a message
OMAG server platform ready for more configuration. This message means it has successfully started.
Once you can see that it has started, use Control-C to stop it.
$ docker run --publish 19443:9443 odpi/egeria
Picked up JAVA_TOOL_OPTIONS:
ODPi Egeria
____ __ ___ ___ ______ _____ ____ _ _ ___
/ __ \ / |/ // | / ____/ / ___/ ___ ____ _ __ ___ ____ / _ \ / / __ / / / _ /__ ____ _ _
/ / / // /|_/ // /| | / / __ \__ \ / _ \ / __/| | / // _ \ / __/ / /_/ // // | / _\ / /_ / | / _// || |
/ /_/ // / / // ___ |/ /_/ / ___/ // __// / | |/ // __// / / __ // // / \ / /_ / _// / // / / / / /
\____//_/ /_//_/ |_|\____/ /____/ \___//_/ |___/ \___//_/ /_/ /_/ \__/\//___//_/ \__//_/ /_/ /_/
:: Powered by Spring Boot (v2.3.0.RELEASE) ::
10:12:28.047 [main] INFO o.s.b.w.e.tomcat.TomcatWebServer - Tomcat initialized with port(s): 9443 (https)
10:12:41.688 [main] INFO o.s.b.w.e.tomcat.TomcatWebServer - Tomcat started on port(s): 9443 (https) with context path ''
Thu Jun 04 10:12:32 BST 2020 No OMAG servers listed in startup configuration
Thu Jun 04 10:12:41 BST 2020 OMAG server platform ready for more configuration
^C
$
Working with the Docker Desktop Dashboard¶
The docker desktop dashboard makes it easy to control your docker containers.
It is started from the docker desktop menu. Select the Dashboard option.
You will see something like this:
Each time a new docker container is created, it is given a generated name.
In the example above the name is gifted-lovelace which is a great tribute to
Ada Lovelace.
You can see that the container is not running (EXITED) because you stopped it earlier with Control-C.
Hover your mouse pointer over the container entry and some options appear.
The triangular "START" button is to start the container running again and the Bin/Trash can is to delete your container. Press the "START" button to start your container again.
When the container is running, more options are available to you when you hover the mouse over the container entry.
The first symbol is the "OPEN IN BROWSER" option. Click on it and your browser opens. You should see an error displayed:
Update the URL as follows:
and press enter. After a few moments, Egeria's Swagger page should open. This is an automatically generated page that describes the REST APIs of Egeria's OMAG Server Platform. There is more information on swagger in the Swagger Tutorial.
Page down until you see the "Platform Services". The platform services provide support for administrators running Egeria.
Click on the angle bracket on the right hand end of the entry and the list of REST API operations is displayed.
Now click on the first blue entry for platform origin. Then press the Try it Out button.
and enter garygeeke in the userId field and then the Execute button.
You can see that through the Swagger UI it is possible to try out different REST requests and make sure the platform is operating correctly. The platform origin request is particularly useful for verifying what version of the OMAG Server Platform is running.
The Swagger UI is useful for ad hoc testing. However, later in the Dojo we will cover a tool called Postman that provides a more powerful testing experience.
So back to the Docker Desktop. The second option on the docker desktop is "CLI".
This opens the Terminal/Command
window inside the docker container. You are in the home directory of the OMAG Server Platform.
This contains the contents of the egeria install image. It is also the home directory of
the OMAG Server Platform which is where it will write its files. Type ls to list the files.
$ ls
LICENSE clients server utilities
NOTICE conformance-suite user-interface
$
(If you want to know more about the egeria install image, see the Installing Egeria Tutorial.)
The third button on the docker desktop is the "STOP" button and the fourth button is "RESTART". If you just need to test these buttons, remember to ensure that the docker container is running when you have finished because it is needed for the rest of the session.
The final button is "DELETE". As described above, it deletes the container and uoi need to start again with
docker run --publish 19443:9443 odpi/egeria.
If you now click on the whitespace of the container's entry, a new section opens up with 3 tabs.
"Logs" shows the console logs. Each new run of the container appends new log information to the end of this console.
"Inspect" shows the settings for the container.
"Stats" shows the resource usage of the container.
... and that is all you need to know about docker.
Raise an issue or comment below