Build and install the Web Interface

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.

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 DEPENDENCIES 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:

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:

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

Afterwards 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 clean up everything.

Build the documentation

Install the below requirements and build documentation in build/ with make doc. You may need to set the environment variables used in src/doc/Makefile, especially JSDOC_BIN in case you didn’t install jsdoc globally.

Requirements

  • sphinx

  • sphinx-autoapi

  • jsdoc (npm install jsdoc)

  • @indiscale/jsdoc-sphinx (npm install @indiscale/jsdoc-sphinx)

  • sphinx-js

  • recommonmark