HodDB

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:
​Making Brick models​
​Brick query language​
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
Using
Configuration
Last modified 1yr ago
Copy link
Contents