search

Start HSML.d using docker compose

hashtag
Table of Contents

hashtag
Overview

This guide walks through an example provided in the SDK repo in the examples/01_start_hsml.d_using_docker_compose directory.

Note that HSML.d is not meant to be used directly, but rather it is a backend dependency for HSTP.d.

hashtag
Files

The files in the examples/01_start_hsml.d_using_docker_compose are as follows:

  • docker-compose-hsml-with-fuseki-persistent-store.yaml: A docker compose file which combines the HSML.d image (published to VERSES' internal ECR instance) with a recent Apache Jena docker image to provide a working instance of hsml.core with Jena as the backing rdfstore.

  • fuseki-config--persistent-store.ttl: this is a configuration file for Apache Jena Fuseki

  • Makefile: A Makefile with a single target (start-hsmld-with-fuseki-locally-via-docker-compose--persistent-store) which encapsulates starting the stack up using docker compose

hashtag
Steps

hashtag
Step 0: Requirements

hashtag
🌐 Web browser

We will be using a web browser to demonstrate the HSML.d and Jena APIs. Note that this is for development / educational / testing purposes only. Generally HSML.d is run in the background and is only accessed directly by HSTP.d.

hashtag
🛠️ GNU Make: Build Automation Tool

See HOW TO: Install GNU Make: Build Automation Tool 🛠️arrow-up-right for details.

hashtag
🐳 Docker + compose

See HOW TO: Install Docker + compose 🐳arrow-up-right for details.

hashtag
Step 1: Run Make target to start the stack of HSML.d + Jena Fuseki

Docker compose can get quite complex, so we've wrapped all of that up in a docker compose file (docker-compose-hsml-with-fuseki-persistent-store.yaml) and a makefile which calls it.

This starts the services up and tails both of their logs to standard out so that you can see what is happening. All you have to do is run the make target to start it up.

From the examples/01_start_hsml.d_using_docker_compose/ directory:

hashtag
Example output

Following is an example of the sort of log that you should expect to see after running that command.

Note that you may see extra logging, warnings, e.g. related to mqtt issues, but as long as both services indicate starting up you should be good to go.

hashtag
👀 Step 2: Explore in the GUI!

Now that HSML.d is started up with Apache Jenna Fuseki running underneath it, you can explore the services.

hashtag
Explore hsml.d

hsml.d is built using FastAPI to implement OpenAPI. Out of the box, it provides a quite detailed GUI for interacting with the APIs.

If you've followed the directions above without changing ports etc, you should be able to visit http://localhost:8080/docs#/arrow-up-right to learn a lot about the API surface, including detailed information about the APIs, examples, and an ability to call them directly from the GUI.

Here's an example of what you may see when looking at the RDFStore section of the API: http__localhost_8080_docs__rdfstore-min.png

Here's what the validate JSON endpoint looks like in the GUI: validate_endpoint_overview-min.png

Here's an example of what selecting a payload to test that endpoint looks like: validate_endpoint_selecting_payload-min.png

Here's an example of what the output of a (failed) validation looks like: validate_endpoint_example_results-min.png

hashtag
Explore Jena Fuski GUI

Apache Jena Fuseki provides a basic IDE out of the box which allows for interaction with the underlying datasets.

If you've followed the directions above without changing ports etc, you should be able to visit http://localhost:3030/#/arrow-up-right to interact with the GUI.

We won't go into details about using Fuseki now, but here's a quick sneak peek at what you may expect to see: http__localhost_3030___dataset_ds_query-min.png

hashtag
Step 4: Explore with code!

The hsml_core.hsml_openapi_client python module (in the hsml_core python library) provides a pythonic client to talk to the hstp.d instance.

Alternatively, you can leverage the openapi.jsonarrow-up-right file provided by hsml.d to generate clients in your language of choice, using e.g. the openapi-generatorarrow-up-right.

PreviousExamples

Last updated