OpenSABER Installation


  • Java - 8+
  • Git

Building the library

git clone
cd open-saber
mkdir java/registry/src/main/resources/public/_schemas              
sh <default_schema>

NOTE:*- default_schema can be either true if you want to use existing sample schema or false to create your own schema definitions.

CAUTION: This installs the default configuration. Please create your own definitions in separate files (not in the default files) to prevent inadvertent over-writes.

Database Configuration

Database can be configured in the generated application.yml, update the connectionInfo properties for the same. Sample Postgresql configuration is available to use postgres connection,to use the default connection create a database ‘opensaberdb’ and update the postgres user and password:

uri: ${connectionInfo_uri:jdbc:postgresql://localhost:5432/opensaberdb}
username: ${connectionInfo_username:postgres}
password: ${connectionInfo_password:opensaberdb}

Build and install

cd java
mvn clean install


1 - Configure environment variables for authentication (optional)

Authentication can be enabled/disabled in the application.yml configuration file mentioned in understanding configuration files section below. The default implementation uses Sunbird’s authentication mechanism which is using keycloak for authentication. Keycloak installation details can be found here. Authentication requires the below mentioned environment variables to be configured. Instructions to set up the SSO key can be found here.

sunbird_sso_publickey = ******

2A: Out of the box = Teacher Registry

The default configuration files provided will be sufficient to start a registry instance. The default registry schema provided is for a Teacher registry.

2B: Manual configuration (optional)

Edit the configuration files or create your own custom configuration files and configure the path. Read understanding configuration files in the section below. If you just want to try it out, then skip this section and come back to it later.

  • Configuring custom configuration files

    1. Read understanding configuration files in the section below to create your own configuration files

    2. Add environment variables pointing to the configuration files.


3 - Running the Registry

All dependencies are now installed. All required sample configuration files are also created and if you don’t want to change anything, you may simply follow the following steps to start up an OpenSABER instance as a Teacher Registry.

Running using docker

In order to run using docker you need to install docker in your system. In the case of Linux systems, docker compose also needs to be installed.

cd registry
docker-compose up
Running it as a simple jar file
cd registry/target
java -jar registry.jar

5 - Taking Registry for a spin!

Understanding Configuration Files

Below mentioned configuration files should be created in src/main/resources. The script ./ will create the files to startup a full fledged Teacher Registry, but you can edit these files to suit your domain. The sample files contain comments which further explain each property.

  1. application.yml - Create a YAML configuration file which contains various environment specific configurations for the application. The default profile will be development environment. The configuration needs to be changed to the environment where the application is deployed. Sample configuration details can be found in application.yml.sample.

  2. **[Person Teacher Vehicle]*.json** - These files contain static and declarative validations. For further details on syntax, you can refer to the JSON Schema. Link to these samples is here.
  3. schema-configuration.json - This file contain schema level configurations. We like to make this at one place, along with the definition itself in future. Further details can be found in schema-configuration.jsonld.sample.

Property Configurations in Detail

The following is a list of configuration options which can be tailored for a specific instance of OpenSABER. All these properties are environment variables and hence can be configured either in .bashrc or in Windows environment properties. Most of the properties have sensible defaults.

  1. perf_monitoring_enabled - This property is used to enable/disable performance instrumentation to performance tune various APIs.

  2. registry_context_base - The primary namespace IRI of the registry instance. It will default to http://localhost:8080/.

  3. config_schema_file - The fully qualified filename with the file:// protocol prefix for configuring fields that need to be encrypted. The default filename will be schema-configuration.jsonld and will be loaded from the classpath. This file will be in JSON-LD format.

  4. database - The storage database provider for the OpenSABER instance. The default database will be NEO4J. Refer to application.yml for more details.

  5. connection_timeout - Encryption service connection timeout in milliseconds.

  6. connection_request_timeout - Encryption service connection request timeout in milliseconds.

  7. read_timeout - Encryption service socket read timeout in milliseconds.

  8. encryption_enabled - Toggle for enabling/disabling encryption.

  9. encryption_base - The base URL for encryption/decryption service.

  10. encryption_uri - The fully qualified URI for encrypting data.

  11. encryption_batch_uri - The fully qualified URL to encrypt data in batch mode.

  12. decryption_uri - The fully qualified URI for decrypting data.

  13. decryption_batch_uri - The fully qualified URL to decrypt data in batch mode.

  14. audit_enabled - Toggle to enable/disable internal audit. The audit records will be stored as part of the primary database.

  15. authentication_enabled - Toggle to enable/disable authentication. The authentication is disabled by default. The default authentication provider is the Sunbird Keycloak service.

  16. sunbird_sso_publickey - The public key of the Sunbird Keycloak authentication service.

  17. sunbird_sso_realm - The SSO realm of the Sunbird Keycloak authentication service.

  18. sunbird_sso_url - The fully qualified URL of the authentication service.

Understanding the Vocabulary File

Create a domain specific vocabulary file for the application. Sample vocabulary file can be found vocabulary.owl.sample. This file should be placed in src/main/resources/vocabulary, so that it can be served as a static resource. This is useful for machine readability of your registry and also helps in understanding various terms being used in the vocabulary. This file needs to be hand-created by an adopter. We are looking to simplify this in future. You may ignore this if you’re not looking for machine readable or Linked Data presently. We will help you get there with our next few releases.

Testing the APIs

OpenSABER API specs and OpenSABER API Examples give detailed descriptions on how to use the APIs in Registry.