Setting up the Testbed#

Note

This new documentation page has not yet been fully reviewed and may be incomplete.

This section will briefly guide you through the setup of a new eLabFTW instance and optionally a LinkAhead instance for testing purposes. If you have existing instances you wish to crawl, please jump ahead to the next chapter.

Prerequisites#

To get the LinkAhead repository, this guide will use git. Alternatively, the repository files can also be downloaded from GitLab as an archive and unpacked manually.
Please also ensure docker is installed and can be used by your current user. You can test this by executing docker run hello-world. If docker is not installed, refer to the docker installation guide. Should hello-world generate a permission error, you may need to add the current user to the docker group. Additionally, docker-compose must be installed and usable.

eLabFTW#

First you will set up eLabFTW. This guide should only be used to set up eLabFTW for testing purposes, should you wish to use eLabFTW permanently, please refer to the official eLabFTW documentation for a current and in-depth installation guide.

Warning

The eLabFTW test instance as used in this guide uses default eLab settings. If you already have an instance of eLabFTW configured, you may have to change settings in the elab compose.yml to prevent it from interfering with your existing instance. Most importantly, if there are files from previous instances in /var/elabftw/, you should likely configure eLab to use a different directory. This is done in the services:web:volumes and services:mysql:volumes sections of the compose file.

Installation#

Download an example docker compose file into the current directory using

curl --silent "https://get.elabftw.net/?config" -o compose_elab.yml
sed -i 's/- SITE_URL=/- SITE_URL=https:\/\/localhost/' compose_elab.yml

Then start the eLabFTW container with

docker compose -f compose_elab.yml up -d

The first startup may take a while. Once it completes, initialize the database with

docker exec elabftw bin/init db:install

Afterward, you can test that the installation was successful by visiting https://localhost/. Your browser should warn you of an insecure connection as the used certificate is self-signed. Accept the warning and check that no error messages are displayed.

Initial Setup#

Now, register a user account in the eLab webUI. You can then log in and create some experiments, resources and files as test data to sync to LinkAhead in the following steps.

If you wish to get acquainted with eLabFTW in detail, refer to the extensive eLabFTW admin and user documentation.

Further use#

To stop the eLabFTW container, use

docker compose -f compose_elab.yml down

All changes you made in eLabFTW will persist.

From then on, you can restart eLabFTW using

docker compose -f compose_elab.yml up -d

LinkAhead#

The following is a basic guide on how to install LinkAhead using the GitLab repository. For an extensive installation tutorial, if you encounter any problems, or if you would like further explanation, please refer to the main setup documentation.

Installation#

Start by cloning the linkahead-control repository into the current folder using

git clone https://gitlab.com/linkahead/linkahead-control.git

Now pull the LinkAhead docker image by running

cd linkahead-control
./linkahead start

In the meantime, create a file with the name .pylinkahead.ini in either the current or your home directory and enter the following content:

[Connection]
# Host URL of the LinkAhead server
url=https://localhost:10443/

# Log in credentials
username=admin
password_method=plain
password=caosdb

# Do not validate SSL certificate of the server - only use for test instance!
ssl_insecure=True

This file specifies which connection details and credentials the python client will use to execute scripts.

Once the pull has concluded, you can check that LinkAhead is running by visiting the Homepage. You may again be warned that the certificate is self-signed, this is normal. The default login credentials are user: admin and password: caosdb.

Further use#

To stop LinkAhead, use

./linkahead stop

In the eLab crawler configuration, changes made to LinkAhead will not persist between restarts.

From then on, you can restart LinkAhead using

./linkahead start

Optionally, you can specify a profile to use with the -p parameter. This will be shown in the section below.If LinkAhead is started with a profile, it should also be stopped with the same profile specified.