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

```{tags} how-to, administrator, developer, linkahead, installation
```

# Installation

## Prerequisites

```{include} /tutorial/administration/installation.md
:start-after: "## Prerequisits ##"
```

## Using services

For automatic restart and certificate renewals it may be a good idea to use services. You might want
to look at systemd documentation if you are not familiar with services.

You can find templates for services and timers in `utils/install`. Also see notes under "Using
services" in `README_SETUP.md`.

```console
$ systemctl start linkahead.service
```

To shut down LinkAhead, analogously type `systemctl stop linkahead.service`.

## Configuration

See [Configuration](/how_to/admin_guides/deploy/configuration.md) for more details on how to
configure your profile.

## Troubleshooting

### Unable to fetch some archives

If apt finishes with this error, run `apt update` and try the installation again.

### Old data still exists

Data is kept in persistent docker volumes. You can remove existing data the following way:

```{warning}
This cannot be undone. Make sure you have backups.
```

Have a look at the docker volumes: `docker volume ls`. The name depends on your profile, but
typically you want to remove the following two:
`docker volume rm default_caosdb-sqldata default_caosdb-caosroot`

### Strange characters in my browser

If you see strange characters in your browser when trying to access LinkAhead, you should explicitly
specify https, like so: <https://localhost:10443> If you try to access LinkAhead via plain http
(`http://localhost:10443`), your browser will receive encrypted content and display it like this:

:::{figure} /.assets/images/how_to/admin_guides/screenshot_plain_http.png
:align: center
:alt: Screenshot of what a browser may show if you try to access LinkAhead via plain
:  http.
:::

### docker-compose is not recent enough

You can install an up-to-date version with (at least 1.27 is required):

```console
$ pip install --user docker-compose
```

### Extroot from NFS mounts fails

If LinkAhead fails to start when trying to use an NFS mount as extroot, possibly with errors like
`Cannot create container for service caosdb-server: invalid mount config for type "bind": stat /data/foo/bar: permission denied`,
then restrictive access permissions may be the reason. In this example, the directory
`/data/foo/bar` could not be accessed, because the mounted NFS resource `/data/foo/` was missing
permissions.

As a workaround, you could mount `/data/foo/bar` directly instead of relying on the `/data/foo`
resource:

```{code-block} cfg
:caption: NFS line for ``/etc/fstab``

server:/volume/foo/bar    /data/foo/bar    nfs   defaults    0 0
```

Or you could create a local bind mount which exposes `/data/foo/bar`

```{code-block} console
:caption: |-
:  Mount ``/data/foo/bar`` to ``/my_extroots/bar``, where ``/my_extroots/`` should be
:  readable to root.

# mount --bind /data/foo/bar /my_extroots/bar
```

% LocalWords:  extroot