Configuration#
Settings#
Most of the configuration is done through Settings (accessible by Administrator).
Configuration Files#
Configuration files are used for setting the server-side configuration. Since the 3.0 release, the configuration for server and document worker components has overlapped. Therefore, we can have a single configuration file for both.
Server Configuration#
For reference, see the configuration of the DSW Deployment example.
General#
This configuration section is used only by Server and covers basic configuration of the application.
- serverPort#
- Type:
Int
- Default:
3000
Port that will be the web server listening on.
- clientUrl#
- Type:
URI
Address of client application (e.g. https://localhost:8080).
- secret#
- Type:
String
Secret string of 32 characters for encrypting configuration in the database and JWT tokens.
Warning
We should keep our secret
secured! Changing secret
will require re-configuration of secrets stored in the database, e.g., token for Registry.
If we need to change our secret
, we need also replace all values encrypted by the secret that is stored in the database as follows:
Note somewhere values from Settings: Client ID and Client Secret of OpenID configurations, Registry token, and GitHub token for Feedback functionality, etc. Adjust the settings that the values are not there (recommended; e.g., remove OpenID configuration), and save it.
Change the
secret
in the configuration file and restart the DSW server (re-create the container if using Docker).Adjust the settings back to our previous values.
If we also use some “user properties” (for the Document Submission feature), let our users know to change the values in their profiles.
Database#
Information for connection to PostgreSQL database.
- database.connectionString#
- Type:
String
PostgreSQL database connection string (typically:
postgresql://{username}:{password}@{hostname}:{port}/{dbname}
, for example,postgresql://postgres:postgres@localhost:5432/postgres
).
S3#
Information for connection to S3 storage (used for document and document template assets).
- s3.url#
- Type:
URI
Endpoint of S3 storage, e.g.,
http://minio:9000
- s3.username#
- Noindex:
- Type:
String
Username (or
Access Key ID
) for authentication
- s3.password#
- Type:
String
Password (or
Secret Access Key
) for authentication
- s3.bucket#
- Type:
String
- Default:
engine-wizard
Bucket name used by DSW
Mail#
This configuration section is used only by Mailer. It must be filled with SMTP connection information to allow sending emails (registration verification, password recovery, project invitation, etc.).
- mail.enabled#
- Type:
String
It should be set to
true
unless used for local testing only.
- mail.name#
- Type:
String
Name of the DS Wizard instance that will be used as “senders name” in email headers.
- mail.email#
- Type:
String
Email address from which the emails will be sent.
- mail.host#
- Type:
String
Hostname or IP address of SMTP server.
- mail.port#
- Type:
Int
Port that is used for SMTP on the server (usually
25
for plain or465
for SSL).
- mail.ssl#
- Type:
Boolean
- Default:
false
If SMTP connection is encrypted via SSL (we highly recommend this).
- mail.authEnabled#
- Type:
Boolean
If authentication using username and password should be used for SMTP.
- mail.username#
- Type:
String
Username for the SMTP connection.
- mail.password#
- Type:
String
Password for the SMTP connection.
Externals#
This configuration section is used only by Document Worker. We can affect steps for templates that use external tools (pandoc
and wkhtmltopdf
). It is usually sufficient to keep the defaults. Each of them has configuration options:
- executable#
- Type:
String
Command or path to run the external tool.
- args#
- Type:
String
Command line arguments used to run the tool.
- timeout#
- Type:
Int
Optional for limiting time given to run the tool.
Integrations Configuration#
Integrations in the DS Wizard use external APIs. Sometimes, we might need some configured variables, such as API keys or endpoints. For example, integration with ID dbase
might use the following configuration.
dbase:
apiKey: topSecretDBaseApiKey
apiUrl: https://api.dbase.example:10666
someConfig: someValue4Integration
There can be multiple integrations configured in a single file. These can be used then when setting up the integration in the Editor as ${apiKey}
, ${apiUrl}
, etc. More about integrations can be found in separate integrations documentation.
Note
Different knowledge models may use different variable naming. Please read the information in README to find out what is required. We recommend authors to stick with apiKey
and apiUrl
variables as our convention.
Client Configuration#
If we are running the client app using “With Docker”, the all we need is to specify API_URL
environment variable inside docker-compose.yml
. In case we want to run the client locally, we need to create a config.js
file in the project root:
window.dsw = {
apiUrl: 'http://localhost:3000'
}
The client also provides a wide variety of style customizations using SASS variables or message localization. Then we can mount it as volumes in case Docker as well:
volumes:
# mount SCSS file
- /path/to/extra.scss:/src/scss/customizations/_extra.scss
- /path/to/overrides.scss:/src/scss/customizations/_overrides.scss
- /path/to/variables.scss:/src/scss/customizations/_variables.scss
- /path/to/provisioning.json:/configuration/provisioning.json:ro
# mount other assets, we can then refere them from scss using '/assets/...'
- /path/to/assets:/usr/share/nginx/html/assets
_extra.scss
= This file is loaded before all other styles. We can use it, for example, to define new styles or import fonts._overrides.scss
= This file is loaded after all other styles. We can use it to override existing styles._variables.scss
= A lot of values related to styles are defined as variables. The easiest way to customize the style is to define new values for these variables using this file.
For more information about variables and assets, visit Theming Bootstrap. The color of illustrations can be adjusted using $illustrations-color
variable.
Document Templates#
We can freely customize and style templates of documents (DMPs). HTML and CSS knowledge is required, and for doing more complex templates that use some conditions, loops, or macros, knowledge of Jinja templating language (pure Python implementation) is useful. For more information, please read the following section.
Email Templates#
Similarly to document templates, we can customize templates for emails sent by the Wizard located in templates/mail
folder. It also uses Jinja templating language. And we can create HTML template, Plain Text template, add attachments, and add inline images (which can be used inside the HTML using Content-ID equal to the filename).
Templates Structure#
The structure is following:
templates/mail/_common
= layout, styles, common filestemplates/mail/_common/attachments
= attachments for all emailstemplates/mail/_common/images
= inline images for all emailstemplates/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 typetemplates/mail/<name>/images
= inline images specific for email type
All attachments are loaded from the template-specific and common folders and included in to email with the detected MIME type. It similarly works for inline images, but those are not displayed as attachments, just as related part to the HTML part (if present). We highly recommend using ASCII-only names without whitespaces and with standard extensions. Also, sending a minimum amount of data via email is suggested.
Templates variables#
All templates are provided also with variables:
appTitle
= from the configurationappTitle
clientAddress
= from the configurationclientUrl
mailName
= from the configurationname
user
= user (subject of an email), structure with attributes accessible via . (dot, e.g.user.name
)
Email types#
Currently, there are following types of mail:
registrationConfirmation
= email sent to user after registration to verify email address, containsactivationLink
variableregistrationCreatedAnalytics
= email sent to address specified in the configuration about registration of a new user (see Analytics config)resetPassword
= email sent to user when requests resetting a password, containsresetLink
variabletwoFactorAuth
= email sent to user when the 2FA is enabled
Docker deployment#
Including our own email templates while using dockerized Wizard is practically the same as for DMP templates. We can also bind whole templates/mail
folders (or even templates
if we want to change both):
mailer:
image: datastewardshipwizard/mailer
restart: always
volumes:
- /dsw/application.yml:/app/config.yml:ro
- /dsw/templates/mail:/app/templates:ro
# ... (continued)