---
last_review: "2025-03-13"
last_reviewer: "-"
documented_code: []
---

```{tags} tutorial, user, administrator, developer, linkahead, installation
```

# LinkAhead Setup

In this tutorial you will learn how to set up the LinkAhead Server on a Linux operating system
(macOS *should* work as well). You typically only need to do this if you are the system's
administrator or if you want to try LinkAhead out and install the LinkAhead Server on your own
machine.

## Installation

The following is a brief tutorial. If you would like further information, please refer to the
in-depth [installation guide](/how_to/admin_guides/installation.md) in the
[admin handbook](/how_to/admin_guides/index.md).

If you have a Debian based operating system, you can follow the
[LinkAhead deb package installation guide](installing_debian_package.md) instead.

## Prerequisits ##

The following dependencies need to be installed:

- acl (for `setfacl` executable)
- curl
- Docker >= 19.03
- Docker compose >= 1.29
- python >= 3.10
- git

We suggest to check out the [official Docker documentation](https://docs.docker.com/engine/install/)
on how to install the Docker dependencies.

On a Debian system, you can install the requirements with:

```sh
sudo apt install curl docker.io docker-compose git python3-pip
```

Next, add your user to the docker group so that the user is allowed to execute docker commands.

```sh
sudo usermod -aG docker $USER
```

```{note}
You might need to log out and log in again in order to gain the new group (see also
[post installation hints](https://docs.docker.com/engine/install/linux-postinstall)).
```

Now clone the LinkAhead deployment repository (if you have not already):

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

Then, install additional Python dependencies using the `--break-system-packages` option or using a
[virtual environment](https://docs.python.org/3/library/venv.html):

```sh
cd linkahead-control
pip3 install -r requirements.txt
```

## Start

Now, you can run

```sh
./linkahead start
```

This will download a Docker image from the internet (takes a moment) and start LinkAhead.

Once the log output says `Starting org.caosdb.server.CaosDBServer application` the installation is
done and LinkAhead is running with the default configuration.

You can now reach the web interface at [https://localhost:10443](https://localhost:10443).
On first access, your browser may warn you that the connection is insecure because the website uses
a self-signed certificate. Select `Accept the risk` to continue.

On the welcome page, you will be asked to log in. Per default, the preconfigured admin credentials
are username `admin` and password `caosdb`. The web interface tutorials can be found in the tutorial section, [here](/tutorial/webinterface/index.md).

Use `./linkahead stop ` to stop LinkAhead and `./linkahead --help` will inform you about further
options.