Developer documentation

Welcome to the developer documentation of the LabInform ELN. This part gives some general background information for developers who want to actively contribute to the project.

Code organisation

Currently, the repository contains two parts: the DokuWiki contents of a demo installation of the LabInform ELN, and the documentation. The former can be run and developed locally using a Docker container. An abbrevated directory listing is provided below as a first overview:

.
├── docs
│   ├── ...
└── dokuwiki
    ├── conf
    ├── data
    │   ├── media
    │   ├── meta
    │   └── pages
    └── Dockerfile

As obvious, the documentation (i.e. what you are actually reading) resides in the docs directory, while the DokuWiki contents for the LabInform ELN together with the Dockerfile for local development reside in the dokuwiki directory.

Later, there may be more directories, e.g. in case of a Python module/package for interacting with the LabInform ELN via XML-RPC interface. For ideas see the Roadmap.

Documentation

(This) Documentation is available online (https://eln.docs.labinform.de) and created using Sphinx. Locally, it resides in the docs directory. To create the documentation locally, you need to have a working Python installation with a few packages. As always with Python projects, it is highly recommended to create a virtual environment and install the required packages locally there. Assuming a working Python installation and a unixoid operating system, the necessary steps are as follows:

# Create virtual environment
python3 -m venv labinform-eln-documentation

# Activate virtual environment
source labinform-eln-documentation/bin/activate

# Install required packages
pip install sphinx sphinx-rtd-theme

To create the actual documentation locally, ensure to have the virtual environment active, change into the documentation directory (docs) and create the documentation. Again, a unixoid operating system is assumed:

# Change to documentation directory
cd docs

# Create documentation locally
make html

To view the just built documentation, point your browser to the correct directory, as shown in the last output line of Sphinx (usually the subdirectory _build/html).

Docker container

To ease development of the LabInform ELN, a Docker container is provided that can be run locally. The same (or at least a very similar) Docker container will eventually run the demo instance available online at https://eln.labinform.de/.

Warning

Please note that none of these docker containers are yet in a state that they should be used for deploying production-ready containers. At least, in a production environment, you would like to have a backup strategy in place.

There are two ways of working with the Dockerfile: using plain docker, and using docker compose. Here, the first option is described. For how to use docker compose, see below.

Use plain docker

To start the Docker container, change to the dokuwiki directory and run the following command, assuming you have a working Docker installation and had built the container previously:

docker run --name eln -d -p 8081:8080 \
    -v "`pwd`/data/pages:/srv/www/data/pages" \
    -v "`pwd`/data/media:/srv/www/data/media" tillbiskup/labinform-eln

This will start the Docker container, name it eln, mount a few local directories and bind the HTTP port of the container to the local port 8081. To view your LabInform ELN, direct your browser to the address http://localhost:8081/.

Note

Important: The above command needs to be issued from within the dokuwiki directory or otherwise the paths for the volumes need to be adapted. Otherwise, your wiki will not work properly (not finding any content and complaining right away).

To stop and remove the container:

docker stop eln; docker rm eln

If the container won’t start and you get a message instead that the name is used already, this usually means that either a container with the same name exists already or that you had it run previously. In this case, simply delete the old container:

docker rm eln

If you didn’t build the container already, obviously you need to do this before you can run it:

docker build . -t 'tillbiskup/labinform-eln'

Todo

Currently, the Dockerfile Dockerfile builds upon images only locally available. However, there is now another Dockerfile called Dockerfile-standalone that does only depend on the (latest) alpine image and incorporates all other steps necessary to create a fully functional Docker container for the LabInform ELN.

Use docker compose

There are two ways of working with the Dockerfile: using plain docker, and using docker compose. Here, the second option is described. For how to use plain docker, see above.

Run the container

Usually, running the container is as simple as:

docker compose up -d

Here, -d implies running as demon.

Note that there is no need to build the image beforehand, as that is been taken care of automatically by docker compose. However, if you need to rebuild the image, see below.

(Re)build the image

As mentioned above, initially building the image before running the container is not necessary, as docker compose takes care of that for you. However, to rebuild the container (particularly important for testing), run this commmand:

docker compose build

Stop (and remove) the container

To just stop the container, run this command:

docker compose down

To remove the container as well, run the following command:

docker compose rm