Installation

Attention

If you’ve deployed a local instance of the Wizard (Docker or build from source), we kindly request you to fill out this DS Wizard instance registration.

Public Instances

The application is currently deployed on a server provided by CESNET. Here are the addresses of running applications:

• Landing page with additional information

• Demo instance (free to use, for trying out all the features, unstable)

• Researchers instance (free to use, to build own DMPs, prepared for serious work)

Tip

You are free to register and test out the Wizard within the ds-wizard.org. Then you can decide if you want a local instance for you or your organization. Eventually you can contact us about DSW Cloud service where we can host and maintain your DSW instance, see our Get Started page.

Via Docker

The simplest way is to use Docker Compose. Requirements are just to have Docker installed, privileges for current user and the Docker daemon started.

1. Create a folder (e.g., /dsw, all commands in this manual are from this working directory)

2. Prepare all config files described in Configuration (especially application.yml), paths are visible from the docker-compose.yml

3. Copy (and adjust) docker-compose.yml provided below

4. Run the DSW with Docker compose docker-compose up -d

5. After starting up, you will be able to open the Wizard in your browser on http://localhost

6. You can use docker-compose logs to see the logs and docker-compose down to stop all the services

docker-compose.yml

version: '3'
services:

  server:
    image: datastewardshipwizard/wizard-server
    restart: always
    ports:
      - 3000:3000
    volumes:
      - /dsw/server/application.yml:/application/engine-wizard/config/application.yml:ro
      - /dsw/server/integration.yml:/application/engine-wizard/config/integration.yml:ro
      - /dsw/templates/dmp:/application/engine-wizard/templates/dmp:ro

  client:
    image: datastewardshipwizard/wizard-client
    restart: always
    ports:
      - 80:80
    environment:
      API_URL: http://localhost:3000

  docworker:
    image: datastewardshipwizard/document-worker
    restart: always
    volumes:
      - /dsw/docworker/config.yml:/app/config.yml:ro
      - /dsw/templates/dmp:/app/templates:ro

  rabbitmq:
    image: rabbitmq:3.8.2-management
    restart: always
    environment:
      RABBITMQ_DEFAULT_USER: rabbit
      RABBITMQ_DEFAULT_PASS: password

  mongo:
    image: mongo:4.2.3
    restart: always
    ports:
      - 27017:27017
    volumes:
      - /dsw/data:/data/db
    command: mongod

Tip

You can take a look at https://github.com/ds-wizard/dsw-deployment-example

Locally without Docker

We highly recommend using Docker, but you are open to compile and run everything directly on your device. It is tested on Ubuntu 16.04 and you might encounter problems when using other plaforms and Linux distributions.

General Requirements

• The Haskell tool Stack (for server side)

• NPM (for client side)

• MongoDB (database, needs to be running)

• RabbitMQ (messaging, needs to be running)

• Python (>= 3.7, document worker)

• wkhtmltopdf (>= 0.12.5, for DMP exports in PDF)

• Pandoc (>= 2.6, for DMP exports in other formats aside HTML, PDF, and JSON)

Server

1. Get the server app (dsw-server)

   git clone https://github.com/ds-wizard/engine-backend.git

2. Copy and edit configuration (see Configuration)

   cp engine-wizard/config/application.yml.example engine-wizard/config/application.yml

3. Build (may take some time to download & build dependencies)

   stack build engine-wizard

4. Run (requires MongoDB according to configuration)

   stack exec engine-wizard

Note

Be aware that running engine-wizard requires its assets (e.g. templates/ and config/) to be present in the working directory or where configured.

Client

1. Get the client app (dsw-client)

   git clone https://github.com/ds-wizard/engine-frontend.git

2. Install the app (dependencies)

   npm install

3. Change configuration if the server is not running on http://localhost:3000 (see Configuration)

4. Run the app

   npm run start:wizard

5. Open app in your favorite browser

6. For minified production-ready version, use

   npm run build:wizard

Document Worker

1. Get the document-worker

   git clone https://github.com/ds-wizard/document-worker.git

2. Install it using pip (or using setup.py)

   pip install .

3. Adjust configuration for your setup (see Configuration)

4. Run the app

   docworker config.yml /path/to/templates

If you need to upgrade MongoDB version, follow the official instructions in their documentation.

Default Users

Initially, migrations will fill the database with predefined data needed including three users, all with password “password”:

• albert.einstein@example.com (Administrator)

• nikola.tesla@example.com (Data Steward)

• isaac.newton@example.com (Researcher)

You can use those accounts for testing or to initially made your own account admin and then delete them.

Danger

Having public instance with default accounts is a security risk. Delete or change default accounts (mainly Albert Einstein) if your DSW instance is public as soon as possible.

Registry

When you have your own self-hosted instance, it is essential for you to register within the Registry service. It is source of shared knowledge models and can support your deployment. After registration of your organization with unique ID and email verification, you will get your token. This token is then used in Settings. Then your instance is connected automatically to the Registry service for specific functionality such as accessing shared knowledge models.

Other “Setups”

Initial Knowledge Model

When you have a fresh installation, there are just the default users and no knowledge models. You are free to create a new one from scratch if you want. Other option is to import existing KM dsw:root:X.Y.Z from the Registry. It is the core knowledge model for general data stewardship. The specific latest version (or other version that is the best for you) as well as other shared knowledge models can be found on the landing page of the Registry service. Other option is to import it from file if you have any (according to Usage)

Database Backup

If you want to regularly backup your database (and you should!), all you need to do is to set-up simple script as cronjob:

dsw-backup.sh

#!/bin/bash
# Location of Mongo's data folder (Dockerized Mongo)
MONGO_DATA_DIR=/dsw/mongo/data
# - or your Mongo without using Docker
# - MONGO_DATA_DIR=/data/db
# Target for storing backups
TARGET_DIR=/var/backups/dsw
# Backup
BACKUP_FILE=$TARGET_DIR/backup_$(date +%d%m%y-%H%M).tgz
tar czf $BACKUP_FILE $MONGO_DATA_DIR

Make it executable (chmod a+x dsw-backup.sh) and add it as cronjob with crontab -e:

0 4 * * * /dsw/dsw-backup.sh

(This will do the backup every day at 4:00 AM. For more information, see crontab.guru.)