Configuration

Last updated 11 days ago

Server Configuration

Especially for a future development we prepare a configuration through a configuration file. Because Haskell/Scotty does not provided any prepared mechanism for it we had to implemented it by my own. Currently there are 2 files - app-config.cfgand build-info.cfg which contain all information needed by a running application. For tests there exist special versions suffixed by -test. A format of configuration files is an old-style Windows .INI format.

An advantage of an external configuration is that the configuration do not have to be present during a compilation process and it can be attached later (during a start of the application).

Build Configuration

A build configuration (build-info.cfg file) contains information about the last build of the application. This configuration can be created simply by running a prepared script build-info.sh. Normally this script is run by a CI Tool (Travis CI) during build process.

Example

name = Data Stewardship Wizard Server
version = 1.0.0
builtat = 2017/10/25 19:50:20Z

Application Configuration

Application Configuration (app-config.cfg file) contains 4 sections - Web, Database, JWT and Role. Currently there are not many things which can be configured but it is assumed that it will grow in the future.

Client

In Client section, address of DS Wizard client is set.

Web

In Web section, you can configure on which port the server will be running and the service token that is same as configured for related Server Worker config.

Database

In Database section, the properties of used Mongo database are configured including host, port, database name, and optionally authentication.

Messaging

TheMessaging section contains the properties of used messaging queue (e.g. RabbitMQ) host, port, username, and password. The PLAIN SASL mechanism is used and username and password must not be empty.

JWT

JWT section contains property which holds a value of secret which is need in a process of signing JWT payload.

Role

In Role section we can assign permissions to roles. These sets of permissions will be used as templates for new users in a way that when a new user is created with some role he will get assigned a list of permissions based on this template from the configuration file.

Mail

In Mail section, you can enable and set connection to SMTP server that will be used to send emails (for example, activation email or forgotten password email). Options name and email are used for sender specification, host is the SMTP server, optionally you can change the port and enable SSL connection (must be lower case option ssl, with value true or false), username and password are used for authorization with the SMTP server.

You should enable emails with enabled = true unless you test the application for yourself only. It is used for email confirmations and mechanism of resetting password.

Analytics

The Analytics section can be used to configure information emails for administrators, e.g., that a new user registered into the Wizard.

Feedback

Optionally you can set Feedback section to allow users provide feedback in questionnaires. It requires you to set-up a GitHub repository and have a token authorized to create issues in the repository (which can be private).

Example

[Environment]
# Production / Staging / Development / Test
env = Production
[Client]
address = http://localhost:3001
[Web]
port = 3000
servicetoken = <secret_token>
[Database]
host = mongo
dbname = dsw-server
port = 27017
authenabled = false
username =
password =
[Messaging]
host = rabbitmq
port = 5672
username = guest
password = guest
[JWT]
secret =
version = 1
expiration = 14
[Role]
defaultrole = DATASTEWARD
admin = UM_PERM, ORG_PERM, KM_PERM, KM_UPGRADE_PERM, KM_PUBLISH_PERM, PM_READ_PERM, PM_WRITE_PERM, QTN_PERM, DMP_PERM
datasteward = KM_PERM, KM_UPGRADE_PERM, KM_PUBLISH_PERM, PM_READ_PERM, PM_WRITE_PERM, QTN_PERM, DMP_PERM
researcher = PM_READ_PERM, QTN_PERM, DMP_PERM
[Mail]
enabled = false
name =
email =
host =
port =
ssl =
username =
password =
[Analytics]
enabled = false
email =
[Feedback]
token =
owner =
repo =
issueurl = https://github.com/:owner/:dsw-staging/issues/:issueId

Client Configuration

When running the DSW Client, you have to set environment variable API_URL which should contain absolute URL to the API backend (DSW server) without the trailing slash.

export API_URL=https://api.dsw.example.org

Server Worker Configuration

For running scheduled service tasks, there is a (optional) server worker component. Its configuration is done with API_URL which is the same as for Client config but also SERVICE_TOKEN that must correspond with Server config (Web section).

export API_URL=https://api.dsw.example.org
export SERVICE_TOKEN=<secret_token>

DMP Templates

You can freely customize and style templates of DMPs (filled questionnaires). HTML and CSS knowledge is required and for doing more complex templates that use some conditions, loops, or macros, knowledge of Ginger templating language (almost the same as famous Jinja) is useful.

Currently, there is just one template consisting of two files:

  • templates/dmp/root.css = CSS style used for HTML template

  • templates/dmp/root.html.jinja = HTML template for rendering the filled questionnaire in any way

Templates allow you to iterate through questions and answers and find what you need to compose some output. For example, you can generate longer text based on answers of various questions by knowing its texts or UUIDs. To the template, object dmp is injected and can be used as variable - for information about its structure, browse current default template or visit source code.

If you want to include some graphics or JavaScript, we recommend you to put it directly into the HTML template file. In case of graphics, use base64 encoded content (suitable for smaller images like icons and logos):

<img src="data:image/png;base64, iVBORw0KGgoAAAANSU
hEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GI
AXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg=="
alt="Red dot" />

Alternatively, you can of course reference picture that is accessible online. For JavaScript, again you can put there directly some script or reference it, for example, from some CDN:

<style type="text/javascript" src="https://code.jquery.com/jquery-3.3.1.min.js"></style>
<style type="text/javascript">
jQuery(".btn").click(function(){
jQuery(this).toggleClass(".clicked");
});
</style>

You can split your template code into multiple files and the use include directive that opens the file and inserts its content where the directive is placed - like we do for including CSS style in HTML template (only one complex HTML file is generated in the end):

<head>
<title>Data Management Plan</title>
<meta charset="utf-8">
<style>{% include "root.css" %}</style>
</head>

If you deploy the Wizard using Docker, you can mount custom files to templates/dmp folder and overwrite default template within docker-compose.yaml (described in Installation section):

docker-compose.yaml
dsw_server:
image: datastewardshipwizard/server
restart: always
ports:
- 3000:3000
volumes:
- /dsw/app-config.cfg:/dsw/config/app-config.cfg
- /dsw/root.html.jinja:/dsw/templates/dmp/root.html.jinja
- /dsw/root.css:/dsw/templates/dmp/root.css
external_links:
- mongo_mongo_1:mongo
networks:
- default
- mongo_default

Email Templates

Similarly to DMP Templates, you can customize templates for emails sent by the Wizard located in templates/mail folder. It also uses Ginger templating language. And you can create HTML template, Plain Text template and add attachments (which can be used inside the HTML using Content-ID equal to the filename).

The structure is following:

  • templates/mail/_common = layout, styles, common files

  • templates/mail/attachments = attachments for all emails

  • templates/mail/<name> = templates specific for this email type, should contain message.html.j2 and message.txt.j2 files (or at least one of them, mail servers prefer both variants)

  • templates/mail/<name>/attachments = attachments specific

    for email type

Currently, there are following types of mail:

  • registrationConfirmation = email sent to user after registration to verify email address, contains activationLink variable

  • registrationCreatedAnalytics = email sent to address specified in the configuration about registration of a new user

  • resetPassword = email sent to user when requests resetting a password, contains resetLink variable

All templates are provided also with variables:

All attachments are loaded from the template-specific and common folders and included to email using its username and detected MIME type. We highly recommend to use ASCII-only names without whitespaces and with standard extensions. Also, sending minimum amount of data via email is suggested.

Including own email templates while using dockerized Wizard is practically the same as for DMP templates. You can also bind whole templates/mail folder (or even templates if want to change both):

docker-compose.yaml
dsw_server:
image: datastewardshipwizard/server
restart: always
ports:
- 3000:3000
volumes:
- /dsw/app-config.cfg:/dsw/config/app-config.cfg
- /dsw/templates/mail:/dsw/templates/mail
# ... (continued)