Skip to content

Installation

Jump to bottom
jyotsna-tarento edited this page Jul 11, 2018 · 25 revisions

Prerequisites

  • Java - 8+
  • Git

Step 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 which requires the below mentioned environment variables to be configured.

sunbird_sso_publickey = ******
sunbird_sso_realm=sunbird
sunbird_sso_url=https://dev.open-sunbird.org/auth/

Step 2 - Configurations

2A: Out of the box = Teacher Registry

git clone git@github.com:project-sunbird/open-saber.git
sh configure-dependencies.sh

This should install default configuration, which will configure resource files required for a Teacher Registry on your machine.

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.

	registry_config_dir=file://...
	config_schema_file=${registry_config_dir}schema-configuration.jsonld
	validations_create_file=${registry_config_dir}validations_create.shex
	validations_update_file=${registry_config_dir}validations_update.shex
	frame_file=${registry_config_dir}frame.json
	audit_frame_file=${registry_config_dir}audit_frame.json

Step 3 - Build

3A - Installing the dependencies

cd open-saber/java
mvn clean install

3B - Build registry

cd open-saber/java/registry
mvn clean install

Step 4 - 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

cd opensaber/java/registry
docker-compose up

Running it as a simple jar file

cd opensaber/java/registry/target
java -jar registry.jar

Step 5 - Taking Registry for a spin!

Understanding Configuration Files

Below mentioned configuration files should be created in src/main/resources. The script ./configure-dependencies.sh 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 spring.profiles.active configuration needs to be changed to the environment where the application is deployed. Sample configuration details can be found in application.yml.sample.

  2. validations_*.shex - These file(s) should contain static and declarative validations. For further details on syntax, you can refer to the Shape Expressions Primer(Shex Primer). Two separate files are required during creation and updation of entities. An example for the validations can be found in validation_create.shex.sample.

  3. schema-configuration.jsonlencryption_based - This file should contain schema level configurations. Further details can be found in schema-configuration.jsonld.sample.

  4. frame.json - This file is useful to frame the JSONLD output so that all the facts are nested instead of being flatly presented. This helps in readability. frame.json.sample contains short-hand names, their namespaces and the the primary type used throughout the JSON-LD document that is issued into the registry.

  5. audit_frame.json - If audit is enabled in application.yml, this file is useful to frame the audit records so that all the facts are nested instead of being flatly presented. This helps in readability. audit_frame.json.sample contains short-hand names, and their namespaces used throughout the audit record that is issued into the registry.

Property Configurations in Detail

  1. perf_monitoring_enabled - This property is used to enable/disable performance monitoring.

  2. registry_context_base - Point to the primary namespace IRI that the registry is using.

  3. registry_system_base - It is used by the application for defining a namespace for audit records.

  4. config_schema_file - This property specifies the name of the file which contains configuration for fields that need to be encrypted. This file is in JSON-LD format.

  5. database_provider - The database provider is specified using this property.

  6. database_embedded - It is used to indicate whether the application is using embedded database or not.

  7. database_host - Database host name or ip is specified using this property.

  8. database_port - Port used by the host to connect to the database is specified here.

  9. database_directory - This property specifies the directory used by the database to store data in the system.

  10. validations_create_file - This should point to the name of the validations file which is used for create API. For further details, you can refer to understanding configuration files above.

  11. validations_update_file - This should point to the name of the validations file which is used for update API. For further details, you can refer to understanding configuration files above.

  12. frame_file - It is used to specify the name of the file which is used to frame a record while reading from the database. For further details, you can refer to understanding configuration files above.

  13. connection_timeout - This property is used by the application to set the timeout for external API calls used by the application.

  14. connection_request_timeout - This property is used by the application to set the timeout for external API calls used by the application.

  15. read_timeout - This property is used by the application to set the socket read timeout for external API calls used by the application.

  16. encryption_enabled - Encryption can be enabled/disabled using this property.

  17. encryption_base - This specifies the base URL for encryption/decryption.

  18. encryption_uri - This property holds the URL which exposes the encryption service.

  19. encryption_batch_uri - This property holds the URL which exposes the batch encryption service.

  20. decryption_uri - This property holds the URL which exposes the decryption service.

  21. decryption_batch_uri - This property holds the URL which exposes the batch decryption service.

  22. audit_enabled - Audit can be enabled/disabled using this property.

  23. audit_frame_file - It is used to specify the name of the file which is used to frame an audit record while reading from the database. For further details, you can refer to understanding configuration files above.

  24. authentication_enabled - Authentication can be enabled/disabled using this property.

  25. sunbird_sso_publickey - This property is used to configure the public key for authentication.

  26. sunbird_sso_realm - This property is used to configure the authentication realm.

  27. sunbird_sso_url - The URL for authentication is configured using this property.

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.

Testing the APIs

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

Clone this wiki locally