XBOS Docs
Search…
HodDB
HodDB is a query processor and database for Brick models.

Configuration

BOSSWAVE Entity

HodD optionally exposes an API over BOSSWAVE, requiring an entity ($HODDB_ENTITY) with publich/subscribe capabilities on a namespace. Create the entity and place it in a known location that you don't mind being mounted into a docker container (such as /etc/hod).
The permissions MDAL needs are all permissions on some prefix ending in s.hod, e.g.
1
bw2 mkdot -f $PRIVILEGED_ENTITY \
2
-t $HODDB_ENTITY \
3
-u $NAMESPACE/services/s.hod/* \
4
-x PC* \
5
-m 'HodDB operation'
Copied!
The URI argument here (minus s.hod, i.e. $NAMESPACE/services) should be included in the configuration for the HodDB service

Config File

HodDB configuration is documented on the HodDB site. it is replicated here
HodDB is configured with a YAML file. By default, this file is called hodconfig.yml and is loaded from the directory HodDB is executed from, though this can be changed with the --config/-c command line option when executing the hod binary. All paths below are relative to the location from which hod is executed.
Configuration defaults are as follows; there's usually no reason to change these aside from the list of buildings to load and the network and BOSSWAVE configuration. Default options are commented out
1
######## HodDB Configuration
2
####
3
# Location and structure of database
4
####
5
# how we load data into the database.
6
# The keys here are the names of the graphs and how they are referred to when
7
# querying. The values are file paths to the source for each graph
8
# CHANGE THIS!
9
Buildings:
10
ciee: buildings/ciee.ttl
11
sdh: buildings/sdh.ttl
12
soda: buildings/soda.ttl
13
# the location of the database files
14
# DBPath: _hoddb
15
# the path to the TTL file containing Brick relationships
16
# BrickFrameTTL: "$GOPATH/src/github.com/gtfierro/hod/BrickFrame.ttl"
17
# the path to the TTL file containing Brick classes
18
#BrickClassTTL: "$GOPATH/src/github.com/gtfierro/hod/Brick.ttl"
19
20
####
21
# Interface Enabling
22
####
23
# Enable HTTP server
24
EnableHTTP: true
25
# Enable BOSSWAVE server
26
EnableBOSSWAVE: true
27
28
####
29
# HTTP Server Configuration
30
####
31
# port to run the server on
32
#ServerPort: 47808
33
# Whether or not to serve on IPv6
34
#UseIPv6: false
35
# Whether or not to serve on localhost. If false, serves on a public interface
36
#ListenAddress: 0.0.0.0
37
# Path to the server directory of hod, which contains the necessary HTML files
38
#StaticPath: $GOPATH/src/github.com/gtfierro/hod/server
39
# If specified, serve the frontend over HTTPS using golang.org/x/crypto/acme/autocert
40
# If left blank (default), just serve over HTTP
41
#TLSHost: ""
42
43
####
44
# BOSSWAVE Server Configuration
45
####
46
47
# BOSSWAVE agent
48
#BW2_AGENT: 172.17.0.1:28589
49
# BOSSWAVE entity. CHANGE THIS!
50
BW2_DEFAULT_ENTITY: path/to/entity/file
51
# Base URI. CHANGE THIS!
52
HodURI: scratch.ns/hod
53
54
####
55
# configuration for verbosity during operation
56
####
57
# Show the namespace prefixes
58
#ShowNamespaces: false
59
# Show the built dependency graph of query terms
60
#ShowDependencyGraph: false
61
# Show the set of operations in the query plan
62
#ShowQueryPlan: false
63
# Show the latencies of creating the query plan
64
#ShowQueryPlanLatencies: false
65
# Show the latencies of each operation in the query plan
66
#ShowOperationLatencies: false
67
# Show the full latency of the query (and its larger components)
68
#ShowQueryLatencies: false
69
# Set log level. In order of increasing verbosity:
70
# Debug, Info, Notice, Warning, Error, Critical
71
#LogLevel: Error
Copied!

Example

Here is a brief example of how to set up the configuration.
The directory 'sample' has the hodconfig.yaml file above. We create a folder called buildings to store our 3 TTL files representing 3 Brick models. This is indicted to HodDB in the Buildings configuration option above.
1
$ tree
2
.
3
├── buildings
4
│ ├── ciee.ttl
5
│ ├── sdh.ttl
6
│ └── soda.ttl
7
└── hodconfig.yaml
Copied!
We can then execute HodDB against this configuration with
1
$ docker run -d --name hod -v `pwd`/sample:/etc/hod -p 47808:47808 gtfierro/hod:latest
Copied!

Installation

HodDB is shipped as a Docker container image gtfierro/hod:latest (most recent version is gtfierro/hod:0.5.6. You can build this container yourself by running make container in a cloned copy of the HodDB repository.

Run with Kubernetes

If you are running Kubernetes on your node/cluster, then you can easily install HodDB by using its Kubernetes file.
Keep in mind that HodDB currently requires a volume mount where the mdal.yaml configuration file is stored.
1
# snippet of HodDB kubernetes file
2
...
3
spec:
4
containers:
5
- name: hod
6
image: gtfierro/hod:0.5.6
7
imagePullPolicy: Always
8
ports:
9
- containerPort: 47808
10
volumeMounts:
11
- name: hodconfig
12
mountPath: /etc/hod
13
volumes:
14
- name: hodconfig
15
hostPath:
16
path: << config directory >> # <-- create this host folder and place all HodDB config there
17
# including the building models and hodconfig.yaml file
Copied!
To execute HodDB as a Kubernetes service, use the following:
1
curl -O https://github.com/gtfierro/hod/blob/master/kubernetes/deployhod.yaml
2
# edit deployhod.yaml and setup HodDB config directory as specified above
3
kubectl create -f deployhod.yaml
Copied!

Run with Docker

If you are not running Kubernetes, you can invoke the MDAL container directly
1
$ docker run -d --name hod -v /path/to/config/dir:/etc/hod -p 47808:47808 gtfierro/hod:latest
Copied!

Using

The HodDB site has several guides on how to use HodDB and Brick:

HTTP Interface

HodDB has a convenient user interface for running, building and visualizing queries. By default this interface is available on port 47808.

Access Control

The HodDB commandline tool has a couple utilities for granting access to a HodDB database as well as granting access to a Brick model.
For access control to a HodDB instance, use the hod check and hod grant commands:
1
NAME:
2
hod check - Check access to HodDB on behalf of some key
3
4
USAGE:
5
hod check [command options] [arguments...]
6
7
OPTIONS:
8
--agent value, -a value Local BOSSWAVE Agent (default: "127.0.0.1:28589") [$BW2_AGENT]
9
--entity value, -e value The entity to use [$BW2_DEFAULT_ENTITY]
10
--key value, -k value The key or alias to check
11
--uri value, -u value The base URI of HodDB
Copied!
1
NAME:
2
hod grant - Grant access to HodDB to some key
3
4
USAGE:
5
hod grant [command options] [arguments...]
6
7
OPTIONS:
8
--agent value, -a value Local BOSSWAVE Agent (default: "127.0.0.1:28589") [$BW2_AGENT]
9
--entity value, -e value The entity to use [$BW2_DEFAULT_ENTITY]
10
--bankroll value, -b value The entity to use for bankrolling [$BW2_DEFAULT_BANKROLL]
11
--expiry value Set the expiry on access to HodDB measured from now e.g. 3d7h20m
12
--key value, -k value The key or alias to check
13
--uri value, -u value The base URI of HodDB
Copied!
Note: There is currently no access control on the HTTP interface.
TODO: document capability URIs for Brick model access
Last modified 1yr ago