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.

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

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

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