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.

Note

Do not forget to add /wizard to your clientUrl

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/wizard).

secret#

Type:

String

Secret string of 32 characters for encrypting configuration in the database.

rsaPrivateKey#

Type:: String

RSA private key for signing JWT tokens according to RS256 algorithm in PEM format (e.g. use ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key without passphrase and paste the contents to this configuration item).

Warning

We should keep our secret and rsaPrivateKey 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

Warning

S3 service must be publicly accessible (so users can download documents and export templates or locales). Also, bucket must be created otherwise documents cannot be created and document templates / locales imported.

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 DSW 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 or 465 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). 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 DSW 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 integration questions 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/wizard-api'
}

Custom Logo#

We can use our own custom logo by mounting it to the client container. The logo must be square and in SVG format.

dsw-client:
    volumes:
    - /path/to/logo.svg:/usr/share/nginx/html/wizard/img/logo.svg

Favicon#

If we changed the logo, we might also want to change the favicon. First, we need to generate the necessary files using, for example, this Favicon Generator. The wizard uses the following files:

android-chrome-192x192.png
android-chrome-512x512.png
apple-touch-icon.png
browserconfig.xml
favicon-16x16.png
favicon-32x32.png
favicon.ico
mstile-144x144.png
mstile-150x150.png
mstile-310x150.png
mstile-310x310.png
mstile-70x70.png
safari-pinned-tab.svg
site.webmanifest

They are all in the /usr/share/nginx/html/wizard/img/favicon folder, so we can mount our generated favicon files from the generator there, or we can mount the whole folder:

dsw-client:
    volumes:
    - /path/to/favicon:/usr/share/nginx/html/wizard/img/favicon

Style Customizations#

We can mount a file called head-extra.html to the wizard client image to attach extra code to the <head> tag. This can be used to override some styles or CSS variables. For example, to change a color theme, we only need to override a few Bootstrap variables:

<style>
    :root {
        --bs-bg-primary-color: rgb(255, 255, 255);
        --bs-btn-primary-active-bg: rgb(18, 128, 106);
        --bs-btn-primary-color: rgb(255, 255, 255);
        --bs-btn-primary-active-color: rgb(255, 255, 255);
        --bs-btn-primary-disabled-color: rgb(255, 255, 255);
        --bs-btn-primary-hover-bg: rgb(19, 136, 113);
        --bs-btn-primary-hover-color: rgb(255, 255, 255);
        --bs-focus-ring-color: 57, 174, 151;
        --bs-input-focus-border-color: rgb(139, 208, 194);
        --bs-link-color: rgb(22, 160, 133);
        --bs-link-color-rgb: 22, 160, 133;
        --bs-link-hover-color: rgb(18, 128, 106);
        --bs-link-hover-color-rgb: 18, 128, 106;
        --bs-primary: rgb(22, 160, 133);
        --bs-primary-bg: rgb(232, 246, 243);
        --bs-primary-bg2: rgb(208, 236, 231);
        --bs-primary-rgb: 22, 160, 133;
        --illustrations-color: rgb(241, 196, 15);
    }
</style>

For more information about what variables can be overridden, see the CSS variables in Bootstrap documentation.

Once we have the file ready, we need to mount it into the container:

dsw-client:
    volumes:
    - /path/to/head-extra.html:/src/head-extra.html

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 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). We can learn more about the template structure and contents directly from the mailer GitHub repository.

Including our own email templates while using dockerized Wizard is practically the same as for DMP templates. We can also bind whole templates folders. (or even templates if we want to change both):

mailer:
    image: datastewardshipwizard/mailer
    restart: always
    depends_on:
    - postgres
    - dsw-server
    volumes:
    - ./config/application.yml:/app/config/application.yml:ro
    - ./templates:/home/user/templates:ro
# ... (continued)