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 Instance¶
The application is currently deployed on a server provided by FIT CTU. Here are the addresses of running applications:
Landing: https://ds-wizard.org
Demo instance (free to use, for trying out all the features, unstable)
Client: https://demo.ds-wizard.org
Server: https://api.demo.ds-wizard.org
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.
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.
Create a folder (e.g.,
/dsw
, all commands in this manual are from this working directory)Prepare all config files described in Configuration (especially,
application.yml
andworker-config.json
), paths are visible from the docker-compose.ymlCopy (and adjust) docker-compose.yml provided below
Run the DSW with Docker compose
docker-compose up -d
After starting up, you will be able to open the Wizard in your browser on http://localhost
You can use
docker-compose logs
to see the logs anddocker-compose down
to stop all the services
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | 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
|
Tip
You can take a look at https://github.com/ds-wizard/dsw-deployment-example
Upgrade¶
Warning
Backup database and other imporant data (e.g., configuration) before upgrade!
In case of using Docker, just use the tag in docker-compose.yml or pull the new Docker image and restart using down/up:
$ docker pull datastewardshipwizard/server
$ docker pull datastewardshipwizard/client
$ docker pull datastewardshipwizard/crontab
$ docker-compose down
$ docker-compose up -d
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 (optional, based on your Configuration)
wkhtmltopdf (>= 0.12.5, for DMP exports in PDF)
Pandoc (>= 2.6, for DMP exports in other formats aside HTML, PDF, and JSON)
Server¶
Get the server app (dsw-server)
git clone git@github.com:ds-wizard/dsw-server.git
Copy and edit configuration (see Configuration)
cp config/app-config.cfg.example config/app-config.cfg
Build (takes a lot of time, downloads & builds all dependencies)
stack build
Run (requires MongoDB and RabbitMQ according to configuration)
stack exec dsw-server
Client¶
Get the client app (dsw-client)
git clone git@github.com:ds-wizard/dsw-client.git
Install the app (dependencies)
npm install
Change configuration if the server is not running on http://localhost:3000 (see Configuration)
Run the app
npm start
Open app in your favorite browser
For minified production-ready version, use
npm run build
Upgrade¶
Warning
Backup database and other imporant data (e.g., configuration) before upgrade!
All you need to do is download or checkout new version from our repositories and rebuild the application (according to guidelines above):
$ git checkout vX.Y.Z
Default Users¶
Initially, migrations will fill the database with predefined data needed including three users, all with password “password”:
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 Registry configuration. Then your instance is connected automatically to the Registry service for specific functionality such as accessing shared knowledge models.
Compatibility¶
The DS Wizard is compatible with all recent versions of web browsers Chrome, Opera, Firefox, and Edge. We do not recomment use of Internet Explorer. Internally, there are components between is are following compatibility of versions:
DS Wizard |
KM Metamodel |
Registry |
---|---|---|
1.8.0 |
3 |
1.0.0 |
1.7.0 |
2 |
– |
1.6.0 |
1 |
– |
1.5.0 (or lower) |
– |
– |
Important
DSW Client and Server should always use matching version (compatibility is assured)!
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)
Public Questionnaire¶
If you also need to enable public questionnaire for Questionnaire demo functionality with this core knowledge model, you have to download public-package-root-1.0.0.json file below and import it directly to the database into publicPackages collection. Optionally, you can move some of your packages similarly.
public-package-root-1.0.0.json
$ mongoimport --db dsw-server \
--collection publicPackages \
--file public-package-root-1.0.0.json
(If using Docker, you will need docker exec.)
Note
For public questionnaire correctly running, you need to import the related Knowledge Model in the Wizard otherwise you will end up with Entity does not exist
error.
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:
1 2 3 4 5 6 7 8 9 10 | #!/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.)