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.

Note

If you have a problem with downloading documents while running the bucket locally, try to add the following line to the /etc/hosts file:

127.0.0.1 host.docker.internal

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.provider¶

Type:

String

Default:

smtp

Possible values are currently: smtp and amazonses. Then based on the provider, the corresponding configuration section must be filled.

mail.smtp.host¶

Type:

String

Hostname or IP address of SMTP server.

mail.smtp.port¶

Type:

Int

Port that is used for SMTP on the server (usually 25 for plain, 465 for SSL, or 587 for STARTTLS).

mail.smtp.security¶

Type:

String

Default:

plain

Security of the SMTP connection. Possible values are: plain, ssl, and tls.

mail.smtp.username¶

Type:

String

Username for the SMTP connection. (If no username/password is given, it is assumed that no authentication is needed.)

mail.smtp.password¶

Type:

String

Password for the SMTP connection. (If no username/password is given, it is assumed that no authentication is needed.)

mail.smtp.timeout¶

Type:

Float

Default:

5

Optional timeout for SMTP connection in seconds.

mail.amazonSes.region¶

Type:

String

AWS region for Amazon Simple Email Service (SES).

mail.amazonSes.accessKeyId¶

Type:

String

Access Key ID for AWS.

mail.amazonSes.secretAccessKey¶

Type:

String

Secret Access Key for AWS.

While the following SMTP configuration still works, it is discouraged to use as deprecated:

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.security¶

Type:

String

Default:

plain

Security of the SMTP connection. Possible values are: plain, ssl and tls. (ssl is used if mail.ssl is true.)

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.

Document Context¶

This configuration section is used only by Document Worker. It allows us to affect some variables that can be used inside document templates.

documentContext.serviceName¶

Type:: String
Default:: Data Stewardship Wizard

Name of the service operating the DSW instance.

documentContext.serviceNameShort¶

Type:

String

Default:

DSW

Short name of the service operating the DSW instance.

documentContext.serviceUrl¶

Type:

String

Default:

https://ds-wizard.org

URL of the service operating the DSW instance.

documentContext.serviceDomainName¶

Type:

String

Default:

ds-wizard.org

Domain name of the service operating the DSW instance.

documentContext.defaultPrimaryColor¶

Type:

String

Default:

#0033aa

Default primary color used in generated documents (if not overridden).

documentContext.defaultIllustrationsColor¶

Type:

String

Default:

#0033aa

Default secondary color used in generated documents (if not overridden).

documentContext.defaultLogoUrl¶

Type:

String

Default:

{{clientUrl}}/assets/logo.svg

Default logo URL used in generated documents (if not overridden).

documentContext.appTitle¶

Type:

String

Default:

DS Wizard

Title of the application used in generated documents (if not overridden).

documentContext.appTitleShort¶

Type:

String

Default:

DSW

Short title of the application used in generated documents (if not overridden).

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