DS Service Registry Admin Guide

Configuration

The Service Registry is realised using LinkSmart Service Catalog (SC). SC is configured using a JSON configuration file, path to which is provided to the SC via -conf flag. By default, the service looks for a configuration file at: conf/service-catalog.json

All configuration fields (except for arrays of objects) can be overridden using environment variables. Below are few examples:

SC_STORAGE_TYPE=leveldb
SC_MQTT_CLIENT_BROKERURI=tcp://iot.linksmart.eu:1883
SC_MQTT_CLIENT_REGTOPICS="a/b,a/c"
❌ SC_MQTT_ADDITIONALCLIENTS setting array of objects is not supported with environment variables

Configuration File

A sample configuration file is available at service-catalog.json.

{
  "description": "string",
  "dnssdEnabled": "boolean",
  "storage": {
    "type": "string",
    "dsn": "string"
  },
  "http" : {
    "bindAddr": "string",
    "bindPort": "int"
  }, 
  "mqtt":{
    "client": {
        "disabled": "bool",
        "brokerID": "string",
        "brokerURI":"string",
        "regTopics": ["string"],
        "willTopics": ["string"],
        "qos": "int",
        "username": "",
        "password": ""
    },
    "additionalClients": [],
    "commonRegTopics":  ["string"],
    "commonWillTopics": ["string"],
    "topicPrefix": "string"
  },
  "auth": {
        "enabled": "bool",
        "provider": "string",
        "providerURL": "string",
        "serviceID": "string",
        "basicEnabled": "bool",
        "authorization": {}
    }
}

where

description is a human-readable description for the SC
dnssdEnabled is a flag enabling DNS-SD advertisement of the catalog on the network
storage is the configuration of the storage backend
- type is the type of the backend (supported backends are memory and leveldb)
- dsn is the Data Source Name for storage backend (ignored for memory, “ file:///path/to/ldb” for leveldb)
http is the configuration of HTTP API
- bindAddr is the bind address which the server listens on
- bindPort is the bind port
mqtt is the configuration of MQTT API
- client is the configuration for the main MQTT client
  - disabled is a boolean flag disabling/enabling the mqtt client
  - brokerID is the service ID of the broker (Optional)
  - brokerURI is the URL of the broker
  - regTopics is an array of topics that the client should subscribe to for addition/update of services
    - Example: "regTopics": ["topic/reg/+"]
    - While publishing a service registration message over this topic, ‘+’ should be replaced by id of the service to be added/updated. id passed in message payload takes precedence over id in the topic
      - E.g., mosquitto_pub -h localhost -p 1883 -t 'topic/reg/custom_id1' -f ./service_object.json
  - willTopics is an array of will topics that the client should subscribe to for removal of services (Optional in case TTL is used for registration)
    - Example: "willTopics": ["topic/dereg/+"]
    - While publishing a service deregistration message over this topic, ‘+’ should be replaced by id of the service to be removed
      - E.g., mosquitto_pub -h localhost -p 1883 -t 'topic/dereg/custom_id1' -m 'something'
  - qos is the MQTT Quality of Service (QoS) for all reg and will topics
  - username is username for MQTT client
  - password is the password for MQTT client
- additionalClients is an array of additional brokers objects.
- commonRegTopics is an array of topics that all clients should subscribe to for addition/update of services (Optional)
  - Example: same as the example for ‘regTopics’ above
- commonWillTopics is an array of will topic that the client should subscribe to for removal of services (Optional in case commonRegTopics not used or TTL is used for registration)
  - Example: same as the example for ‘willTopics’ above
- **topicPrefix** is the string describing the prefix of service announcement topics
auth is the Authentication configuration
- enabled is a boolean flag enabling/disabling the authentication
- provider is the name of a supported auth provider
- providerURL is the URL of the auth provider endpoint
- serviceID is the ID of the service in the authentication provider (used for validating auth tokens provided by the clients)
- basicEnabled is a boolean flag enabling/disabling the Basic Authentication
- authorization - optional, see authorization configuation

Deployment

Docker

docker run -d --name sr -p 8082:8082 linksmart/sc

The index of the REST API should now be accessible at: http://localhost:8082

Custom configuration

For a configuration file located on host at $(pwd)/conf/service-catalog.json

docker run -p 8082:8082 --name serviceregistry -d -v $(pwd)/conf:/conf -v $(pwd)/data:/data --restart=unless-stopped  linksmart/sc:latest -conf /conf/service-catalog.json

Binary Distributions

Available for released versions and for multiple platforms: https://github.com/linksmart/service-catalog/releases

Download and run:

./service-catalog-<os-arch> --help

On Linux and macOS, it needs to have execution permission. E.g. chmod +x service-catalog-<os-arch>

Data Spine Service Registry Documentation

Last updated on 05.08.2020