SolarDRAS Development Guide

SolarDRAS Development Guide

This guide explains how to setup a development environment for contributing or modifying the SolarDRAS application code.

The SolarDRAS project consists of a set of OSGi bundle projects that, when combined and run in an OSGi container, form a complete SolarDRAS application. Each OSGi bundle comes configured as an Eclipse IDE plug-in project (Eclipse refers to OSGi bundles as "plug-ins" and its OSGi development tools are collectively known as PDE). Although Eclipse is not actually required, the remainder of this guide will describe setting up Eclipse for viewing and running the code for development purposes.

Eclipse Setup

SolarDRAS builds on top of the services included in the SolarNet application. If you haven't already set up your SolarNet development environment, go through the SolarNet Developer Guide first, and then return here.

Clone Git repositories

The SolarDRAS project is contained in the solarnetwork-dras repository. You can clone a Git repository by going to Window > Open Perspective > Git Repository Exploring (you may need to choose "Other..." under Open Perspective if Git does not appear there).

1. git@github.com:SolarNetwork/solarnetwork-dras.git

Note this is in addition to the common repositories mentioned in the SolarNet Developer Guide, which also describes in more detail how to clone repositories in Eclipse.

Database setup

SolarDRAS requires a PostgreSQL database, version 9.6 or higher, to operate. Please note that only version 9.6 has been extensively tested. You should have already set up the database per the SolarNet Developer Guide.

There are SQL setup scripts to create the initial database tables located in the net.solarnetwork.central.dras project, in the defs/sql/postgres directory. The dras-reboot.sql script is designed to be run by the psql utility and create all other necessary database tables, functions, and indices used by SolarDRAS.

One additional step is necessary after creating the database tables. Either the database, or user connecting to the database, must have the INTERVAL type encoded in text form using the iso_8601 pattern.

For example, if the solarnet user connects to the database, then you would run the following SQL to set this:

ALTER ROLE solarnet SET intervalstyle = 'iso_8601';

The complete set of commands using psql would look something like this:

psql -U solarnetwork -d solarnetwork -f dras-reboot.sql
psql -U psql -d solarnetwork -c "ALTER ROLE solarnet SET intervalstyle = 'iso_8601'"

PostgreSQL administration is beyond the scope of this article. Please see the PostgreSQL documentation available online for more information.

Tomcat authorization setup

SolarDRAS relies on the servlet container it is running in to provide standard JEE authentication. In addition, single-sign-on support must be enabled so that the different SolarDRAS webapps can provide a single protected URL space. The <Host> element in the solarnetwork-osgi-target/config/tomcat-server.xml file should be updated to include an appropriate <Realm> element for the authentication, and a <Valve> element for the single-sign-on support, like this:

<Realm className="net.solarnetwork.common.web.catalina.OsgiDataSourceRealm"
	dataSourceName="(db=central)"
	digest="SHA-256"
	userTable="solardras.dras_user"
	userNameCol="username"
	userCredCol="passwd"
	userRoleTable="solardras.dras_auth_roles" roleNameCol="rolename">
	<CredentialHandler className="org.apache.catalina.realm.SecretKeyCredentialHandler"
		algorithm="PBKDF2WithHmacSHA256"
		keyLength="256"
		iterations="131072"
		saltLength="64"
	/>
</Realm>
<Valve className="org.apache.catalina.authenticator.SingleSignOn"/>

With the above configuration, user details will be loaded from the solardras.dras_user database table, using username and passwd columns for the username and password values, respectively. The passwords are hashed using the PBKDF2 algorithm configured with the SHA-256 digest algorithm, using 32-byte (256 bit) long password values derived from 8 bytes (64 bits) of random salt and 131072 iterations.

When adding users to this database table, the passwords must be hashed using the same algorithm and parameters as configured on the <CredentialHandler> element. The net.solarnetwork.pki.bc.BCPBKDF2PasswordEncoder class can be used to hash passwords using these settings. Pass the plaintext password as the command line argument, and it will print out the hashed value. For example:

java net.solarnetwork.pki.bc.BCPBKDF2PasswordEncoder test
test = 3945950b2fb29b83$131072$cad7f27dc20a77f300453921853f11b3eafa31b602f2ddbf832535ebcadca1ac

Running or debugging the SolarDRAS application

Once the platform is running, if Tomcat is listing in port 8080 you can log into SolarDRAS at http://localhost:8080/sndras/u/home.do.