---
last_review: "2025-01-01"
last_reviewer: "-"
documented_code: []
---

```{tags} how-to
```

# Setting up the Testbed

:::{note}
This new documentation page has not yet been fully reviewed and may be incomplete.
:::
% TODO: Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/81
% TODO: Is this a tutorial or a how-to? It is written hand-holdey enough to be a tutorial (and
% TODO: should likely stay that way), but the content might be general enough that it qualifies as
% TODO: how-to?

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](setup_elab_crawler.md).

## Prerequisites

To get the LinkAhead repository, this guide will use git. Alternatively, the repository files can
also be downloaded from [GitLab](https://gitlab.com) 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](https://docs.docker.com/engine/install/). Should hello-world generate
a permission error, you may need to [add the current user to the docker group](https://docs.docker.com/engine/install/linux-postinstall/).
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](https://doc.elabftw.net/install.html) 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

```bash
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

```bash
docker compose -f compose_elab.yml up -d
```

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

```bash
docker exec elabftw bin/init db:install
```

Afterward, you can test that the installation was successful by visiting
[https://localhost/](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](https://localhost/register.php). 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](https://doc.elabftw.net/user-guide.html).

### Further use

To stop the eLabFTW container, use

```bash
docker compose -f compose_elab.yml down
```

All changes you made in eLabFTW will persist.

From then on, you can restart eLabFTW using

```bash
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](/tutorial/administration/installing_debian_package.md).

### Installation

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

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

Now pull the LinkAhead docker image by running

```bash
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](https://localhost:10443). 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

```bash
./linkahead stop
```

In the eLab {term}`crawler <Crawler>` configuration, changes made to LinkAhead will not persist
between restarts.

From then on, you can restart LinkAhead using

```bash
./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.