LitDB

Contact

Associated Scientists & Alumni

LitDB - Managing Publications from your Institute

LitDB is a web-based tool for keeping track of papers producted by your institute. It makes it possible for several researchers from an institute to assemble a publication record together so that no paper is missed when writing grant applications.

LitDB is free software. It is released under the terms of the following BSD License 2.0.

 

Installation

There are two ways to install LitDB for your institute:

  1. Normal Installation
  2. Installation with Docker

Please note that the LitDB is a server software. You need to install it on a computer which will be continously running and be reachable in your institute's network.

If you are already familiar with Docker, simply proceed to the corresponding section. Otherwise you can just do the normal installation which involves more steps.

Normal Installation

The LitDB software has been submitted to Source Code for Biology and Medicine. The version of the LitDB that is described in the corresponding paper can be downloaded here. Later versions of the software will also be available here once released.

Installing the dependencies:

  1. Install Python 2.7 and a mod-wsgi compatible web server like Apache
  2. If necessary, install mod-wsgi support for the web server
  3. Install the development libraries for libldap2, libsasl2 and libpq. On Debian-based systems these are the packages libldap2-dev, libsasl2-dev and libpq-dev respectively.
  4. If it is not already installed, install the python package manager pip
  5. Use pip to install the python packages django-auth-ldap and psycopg2
  6. Afterwards use pip to install Django version 1.8.7 (pip install Django==1.8.7)

Configuring the system

  1. Make sure that your web-server works with mod-wsgi and can now run Python-based server software.
  2. Download the LitDB software and put it in the webroot of your webserver
  3. Set the entrypoint for mod-wsgi to ${WEBROOT}/litdb/LitDB/LitDB/wsgi.py
  4. Create a new directory ${LitDB root directory}/litdb/LitDB/media and make sure that the web server has permission to read and write files in that directory.
  5. Make sure that you have a PostgreSQL database running and that you have permissions to create tables in that database
  6. Download a sample configuration file and place it in the webroot of the LitDB installation. Configure it according to the instruction in the litdb_local_settings.py section.
  7. Make sure that the folder ${WEBROOT}/litdb/LitDB/LitDB/ is discoverable from sys.path. You can achieve this by placing a symlink into one of the site-packages directories of your python installation.
  8. Go into the directory litdb/LitDB and execute the following lines:
    python2 manage.py migrate auth 2> /dev/null #NOTE: this will fail partially
    python2 manage.py migrate #this will do all remaining migrations
  9. And finally create an admin account:
    python2 manage.py createsuperuser
  10. You can now start the LitDB server

Installation using Docker

Installing the dependencies:

This guide assumes at least Docker version 1.10. Some network-related functionality might be different in earlier versions.

  1. If not already done, install docker and add yourself to the docker system group. Log yourself out and in again if this step was necessary.
  2. Download the litdb docker utils package and extract it to the directory from which you want to control the LitDB.

Configuring the system

  1. If you do not already have a postgresql database running, you can edit and afterwards run the run_database.sh script to create a new (dockerized) database.
  2. Edit the file litdb_local_settings.py as described in the section litdb_local_settings configuration. If you used the script run_database.sh, use the username, password and container name from that script. The HOST parameter corresponds to the container name in this case.
  3. Run the script configure.sh. If you did NOT use the script run_database.sh, please remove the --link litdb-database:litdb-database line inside the script.
  4. Finally, you can use the script run.sh to start the LitDB. As with the previous script, please remove the line --link litdb-database:litdb-database if you did NOT use the run_database.sh script.
  5. You can use the script stop.sh to stop the LitDB server. This is faster than using docker stop

litdb_local_settings.py configuration

There are a couple of variables that you want to set

Variable Description of value
DEBUG True or False. Should be False for non-development installations installations
ADMINS Several ( username, e-mail address ) pairs for all admins of the LitDB installation
DATABASES_DEFAULT A python dictionary containing the database connection parameters
SMTP_SERVER Server for sending e-mails
EMAIL_ADDRESS E-Mail address that should be used when sending E-Mails
SECRET_KEY Write something random here to improve data transmission security. See the official Django documentation for details
AUTH_LDAP_SETS Connection parameters for LDAP authentification. See below for details.
HEADER_LOGO Path to the image shown at the top of LitDB. You can specify a path to a file on a different web server or, if you use Docker, mount a file inside the docker container and refer to it with HEADER_LOGO.
FAVICON Path to favicon. The same comments as with HEADER_LOGO apply here
STANDARD_CSS Path to the main CSS file. The same comments as with HEADER_LOGO apply here

Getting started with your first papers

The important quicklinks are already displayed on the front page. First you should create aliases for yourself, so that LitDB knows which author names or name-parts it should associate with your account.

If this is a completely fresh LitDB installation, you probably want to upload metatdata of some of your papers. Otherwise you can use the search with already uploaded articles

And finally, there is the PROFILE link where you can enter your complete name that should be shown inside the LitDB user interface

LDAP connection parameters

In the litdb_local_settings.py there is the section AUTH_LDAP_SETS which can be set to the empty tuple () if you do not use LDAP for authentification. If you do want to use LDAP, you can insert any number of Python dictionaries into the tuple. Each of these dictionaries has the following fields:

Field name Field description Field example
NAME Name of the LDAP server you want to connect to 'University Server'
SERVER_URI URL to the LDAP server. Usually prefixed with ldap:// ldap://uni-kiel.de
PORT TCP and UDP port 389
BIND_DN Username for the connection to the LDAP server The username
BIND_PASSWORD Passwort for the connection to the LDAP server The password
LDAP_USER_SEARCHES The directory within the LDAP system that should be searched. It has to be a tuple containing further tuples and the third element of these inner tuples have to be python format strings that will receive the username.
(
  ("ou=ikmb,ou=einrichtungen,dc=uni-kiel,dc=de", SCOPE_SUBTREE, "(cn=%(user)s)"),
  ("ou=ikmb,ou=einrichtungen,dc=uni-kiel,dc=de", SCOPE_SUBTREE, "(mail=%(user)s)")
)
  				
USER_ATTR_MAP A python dictionary that specifies which values should be looked up from the LDAP server. Possible keys for the dictionary are
  • first_name
  • last_name
  • email
  • username
And the values are the names of the fields on the LDAP server that correspond to these keys.
'USER_ATTR_MAP': {
"first_name" : "givenName",
"last_name"  : "sn",
"email"      :
"mail",
"username"
: "cn",
}
			

Full example:

AUTH_LDAP_SETS = (
  {
      'NAME'               : 'RZ Server',
      'SERVER_URI'         : 'ldaps://rzldap.rz.uni-kiel.de',
      'PORT'               : 636,
      'BIND_DN'            : 'cn=ikmbuser.litdb,ou=ikmb,dc=uni-kiel,dc=de',
      'BIND_PASSWORD'      : 'best password ever',
      'LDAP_USER_SEARCHES' : (
          ("ou=accounts,dc=rz,dc=uni-kiel,dc=de", SCOPE_SUBTREE, "(uid=%(user)s)"),
          ("ou=accounts,dc=rz,dc=uni-kiel,dc=de", SCOPE_SUBTREE, "(mail=%(user)s)"),
      ),
      'USER_ATTR_MAP'      : {
          "first_name" : "givenName",
          "last_name"  : "sn",
          "email"      : "mail",
      }
  },
  {
      'NAME'               : 'University Server',
      'SERVER_URI'         : 'ldap://uni-kiel.de',
      'PORT'               : 389,
      'BIND_DN'            : 'user@server',
      'BIND_PASSWORD'      : 'worst password ever',
      'LDAP_USER_SEARCHES' : (
          ("ou=ikmb,ou=einrichtungen,dc=uni-kiel,dc=de", SCOPE_SUBTREE, "(cn=%(user)s)"),
          ("ou=ikmb,ou=einrichtungen,dc=uni-kiel,dc=de", SCOPE_SUBTREE, "(mail=%(user)s)"),
      ),
      'USER_ATTR_MAP'      : {
          "first_name" : "givenName",
          "last_name"  : "sn",
          "email"      : "mail",
          "username"   : "cn",
      }
  },

)