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

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

# Build and install the Web Interface

:::{note}
This page has been migrated from the old documentation, and has not yet been fully revised.
There might be inconsistencies or errors when using with current LinkAhead versions.
:::
% TODO: Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/94
% TODO: Split into README, Tutorial, and How-To
% TODO: This is a README page from the caosdb-webui repository, see
% TODO: [here](https://docs.indiscale.com/caosdb-webui/install.html). The README should be rewritten
% TODO: to be a minimal setup and usage guide, with a link to this documentation page for further
% TODO: information.

Here, we document how to install and build the LinkAhead Web Interface. If you are only interested
in how to use it, please continue [here](/tutorial/webinterface/index.md).

## Folder Structure

* The `src` folder contains all source code for the web interface.
* The `libs` folder contains all necessary third-party libraries as zip files.
* The `test` folder contains the unittests for the web interface.
* The `ext` folder contains extension for the web interface. The make file will copy all javascript
  files from `ext/js/` into the public folder and links the javascript in the `public/xsl/main.xsl`.
* The `misc` folder contains a simple http server which is used for running the unit tests.
* The `build.properties.d/` folder contains configuration files for the build.

## Build Configuration

The default configuration is defined in
`build.properties.d/00_default.properties`.

This file defines default variables which can be used in source files and will be replaced with the
defined values during the build.

All files in that directory will be sourced during `make install` and `make test`. Thus, any
customized configuration can also be added to that folder by just placing files in there which
override the default values from `00_default.properties`.

See `build.properties.d/00_default.properties` for more information.

## Setup

* Run `make install` to compile/copy the web interface to a newly created `public` folder.
* Also, `make install` will copy the scripts from `src/server_side_scripting/` to `sss_bin/`. If you
  want to make the server-side scripts callable for the server as server-side scripts you need to
  include the `sss_bin/` directory into the server property `SERVER_SIDE_SCRIPTING_BIN_DIRS`.

## Test

* See the DEPENDENCIES.md file in the server Repository for the requirements to run the unit tests.
* Run `make test` to compile/copy the web interface and the tests to a newly created `public`
  folder.
* Run `make run-test-server` to start a python http server.
* The test suite can be started with `firefox http://localhost:8000/`.
* *On WSL (as of Feb 2024, WSL v2.0.14.0)*, port 8000 is sometimes not properly forwarded to the
  host resulting in an unreachable test suite. Switching to a different port can be done easily by
  using the `TEST_PORT` environment variable, e.g. with `TEST_PORT=8111 make run-test-server`. Using
  the X11 `firefox` from within WSL always works.
* To run the test suite non-interactively (as in CI/CD) use `make -d run-qunit`

### Tests with docker

You can also run the tests inside a docker image, e.g., when you can't run the unit tests because (
as of 2025-08) building the tests fails on macOS. There is a docker file in `test/docker` with which
you can build an image in which you can run the tests:

```sh
cd test/docker
docker build -t webui_test .  # You can choose any other image tag instead of "webui_test".
cd ../../  # Go back into webui root
```

Then you can start a container in which you execute the WebUI unit tests:

```sh
docker run -ti -v "$PWD:/webui" -p 8000:8000 webui_test bash  # Replace the image tag "webui_test" in case you chose a different tag name above.
# You're now inside the docker coontainer, logged in as root
cd webui
make test
make run-test-server
```

Afterward you can view the test results by visiting <http://localhost:8000> with your browser. You
can change the port by altering the `-p` option in the above `docker run` command, e.g.,
`-p 10080:8000` makes the tests available on <http://localhost:10080>.

## Clean

* Run `make clean` to delete generated files.

### Requirements

* sphinx
* sphinx-autoapi
* jsdoc (`npm install jsdoc`)
* @indiscale/jsdoc-sphinx  (`npm install @indiscale/jsdoc-sphinx`)
* sphinx-js
* recommonmark