Setup

The only requirement is a working version of python 3.9.x. Using anaconda or https://docs.conda.io/en/latest/miniconda.html for a python environment is highly recommended.

The setup consists of 5 parts:

Python environment
Database setup
Annotation protocol
Deploy server
Add data

Python environment

First install the python environment.

With Conda:

conda env create

then activate the environment with

conda activate human

OR install from requirements.txt with pip or whatever you fancy.

pip install -r requirements.txt

Database setup

First initialize the database with

flask init-db

Then add an admin account with

flask add-admin

Annotation protocol

Write your custom annotation protocol into protocol.yml. Refer to the wiki for documentation on how to do this and see our example protocols (under /examples) for inspiration.

Whenever you change any state names in protocol.yml, afterwards be sure to run

flask run reset-annotations

This will reset the annotations table in the database and is necessary to properly save annotations after a change in the protocol.

Deploy server

To run a server you have 2 possibilities:

1. Run locally on your machine

Locally you can start a server with

flask start

and visit http://127.0.0.1:5000 in your favorite browser and login with your admin account. However it is very ill advised to use this with an open port in a production environment.

2. Deploy in a production environment

When running HUMAN in a production environment on a server we recommend using gunicorn (included in the environment). First, you should set a secure SECRET_KEY in config.py. The script start_server.sh should take care of starting the server.

For docker refer to the https://github.com/uds-lsv/human/wiki/Docker/.

Adding data

To add a file with data, start the server, log in with your admin account, and go to "Data Console". There you can upload the file. Be sure that it is a tab separated file with the three columns "content", "context" and "meta".

When you want to display files you can use "Upload Folder" in "Data Console" and then upload a file with <folder-name>/<file-name> in the content fields for every file in the folder.