Installation

Global Instance

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

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.

Register your instance

If you've deployed a local instance of the Wizard (Docker or build from source), we kindly request you to fill out this form:

Docker

We recommend using Docker for running the Wizard. We provide publicly two images via public repository of Docker Hub registry:

Docker Compose

The simplest way is to use Docker Compose. Requirements are just to have Docker installed and the Docker daemon started.

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

  2. Prepare a app-config.cfg file for server described in Configuration and worker-config.json from below

  3. Copy (and adjust) docker-compose.ymlprovided below

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

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

worker-config.json
[{
"comment": "Synchronize all feedbacks with GitHub (runs every day at 2am)",
"schedule":"0 2 * * *",
"command":"wget --header \"Authorization: Bearer ${SERVICE_TOKEN}\" \"${API_URL}/feedbacks/synchronization\""
}]
docker-compose.yml
version: '3'
services:
dsw_server:
image: datastewardshipwizard/server
restart: always
ports:
- 3000:3000
volumes:
- /dsw/app-config.cfg:/dsw/config/app-config.cfg
links:
- rabbitmq
- mongo
dsw_client:
image: datastewardshipwizard/client
restart: always
ports:
- 80:80
environment:
- API_URL=http://localhost:3000
dsw_server_worker:
image: datastewardshipwizard/crontab
restart: always
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
- /dsw/worker-config.json:/opt/crontab/config.json
environment:
- API_URL=http://localhost:3000
rabbitmq:
image: rabbitmq
mongo:
image: mongo:3.0.15
restart: always
ports:
- 27017:27017
volumes:
- /dsw/data:/data/db
command: mongod

Images Details

The server images is based onstack-hpack image. Our image contains both - source codes and compiled application. An advantage is that we do not have to have 2 images - one for build and one for running a compiled application. A disadvantage is a size of Docker image (it has to include source codes and build tools).

For the client, the Docker image is based on nginxthat simply serves the static files built by webpack.

We build our Docker images automatically after a detected change in a master branch. A produced images are then uploaded to the Docker registry.

Local deployment

General requirements

Server

  1. Get the server app (dsw-server) git clone git@github.com:ds-wizard/dsw-server.git

  2. Copy and edit configuration (see Configuration) cp config/app-config.cfg.example config/app-config.cfg

  3. Build stack build

  4. Run (requires MongoDB and RabbitMQ running and configured) stack exec dsw-server

Client

  1. Get the client app (dsw-client) git clone git@github.com:ds-wizard/dsw-client.git

  2. Install the app (dependencies) npm install

  3. Export API_URL environment variable (see Configuration)

  4. Run the app npm start

  5. Open app in your favorite browser

  6. For minified production-ready version, use npm run build

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.

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.

Setup Knowledge Model

When you have a fresh installation, there are just default users and no knowledge models. You are free to create a new one from scratch if you want. Other option is to download elixir-root.km file from ds-wizard/km-elixir-root and import it (see Usage). It is the core knowledge model for general data stewardship.

If you also need to enable Public Questionnaire functionality with this core knowledge model, you have to download public-questionnaire.json file below and import it directly to the database.

mongoimport --db dsw-server \
--collection publicQuestionnaires \
--file public-questionnaire.json

(If you are running Mongo in Docker, you want to use docker exec.)

For public questionnaire correctly running, you need to import the related Knowledge Model otherwise you will end up with "Entity does not exist" error.

Upgrade

We regularly release new versions of the Wizard. You always should have the same major and minor version of the server and client apps, other might be most probably incompatible.

Self-hosted Wizard

All you need to do is download or checkout new version from our repositories and rebuild the application (according to guidelines for the server/client app):

$ git checkout vX.Y.Z
...

Dockerized Wizard

In case of using Docker (which is the recommended way), just use the tag in docker-compose.yml or pull the new Docker image:

$ docker pull datastewardshipwizard/server
$ docker pull datastewardshipwizard/client
$ docker pull datastewardshipwizard/crontab
$ docker-compose down
$ docker-compose up -d

Important notes

Always backup your database before proceeding with the update. Automatic database migrations might remove some data because of incompatibilities between versions. Delete the backup only when you are certain that nothing is lost after the upgrade! With the DB backup it is possible to revert the changes and restore your data.

Database backup

If you want to regularly backup your database, 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:

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

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

Ensure that you run the script with user that you want and that the target backup directory (e.g. /var/backups/dsw) exists.