shacl-vue

Build and deploy shacl-vue ​

The sections below describe the suggested processes involved in:

  1. Setting up shacl-vue for a UI deployment
  2. Configuring and running the build process

1. shacl-vue UI deployment setup ​

The static files for a shacl-vue deployment, such as the one at https://pool.psychoinformatics.de/ui/, can be built from a dedicated git repository (for the given example, this repository is at: https://hub.psychoinformatics.de/www/pool.psychoinformatics.de-ui) that contains the following:

  1. Input files to the shacl-vue build process:
    • required configuration file (for the given example, see config.yaml)
    • optional assets such as a logo or front page HTML file or wizard editor templates
    • optional build configuration file and environment variables
  2. shacl-vue as a git submodule
  3. A makefile (e.g. this) containing the commands necessary for setting up the build environment and building application.

Extra details are provided per repository component:

Input files ​

The config.* file is required and contains all configuration options to customize the shacl-vue deployment. These options are described comprehensively in the Application configuration section. Some noteworthy options include:

  • shapes_url specifies the URL of the SHACL sources that drive the actual UI
  • service_base_url provides the base URLs and read/write type of the dumpthings service endpoints integrated with the specific shacl-vue deployment

A configuration file can be supplied in either YAML or JSON format.

shacl-vue ​

This submodule pins a specific version/tag of the shacl-vue source code to the UI deployment. It should be kept up to date with the latest commit in the main branch if the goal is to support the latest shacl-vue features for the deployed UI instance. On the other hand, it is possible that a specific branch or tag is pinned to the repository for a specific reason, for example a production UI instance that should not be changed for consistency. If that is the case, this version/tag should be noted explicitly and adhered to.

Build configuration ​

shacl-vue supports the use of build-time configuration options that are supplied either directly as ENV variables or via a config file. Such a config file can be supplied here in JSON and YAML format, and should be passed to the build command (see below) using the BUILD_CONFIG variable, e.g.:

BUILD_CONFIG="path/to/local/config/file.yaml" npm run build:app

Makefile ​

This suggested deployment approach uses make for environment setup and deployment steps. The Makefile contains commands for, amongst others:

  • installing vite, shacl-vue and dependencies
  • building the shacl-vue distribution files
  • if required, deploying the distribution files to a particular server

2. shacl-vue UI deployment steps ​

Firstly, ensure that your environment has git and nodejs installed. The latter is typically done through a virtual environment manager.

For the next steps, we use the above repository as an example. First, clone the UI source repository:

bash
git clone https://hub.psychoinformatics.de/www/pool.psychoinformatics.de-ui.git

Then, navigate to the repository and ensure the shacl-vue submodule is available locally:

bash
cd pool.psychoinformatics.de-ui
git submodule update --init shacl-vue

To install and build shacl-vue, you can use make:

bash
make install
make build-ui

The install and build-ui steps are not explicitly necessary to execute separately, because they can also be executed via an added deploy command, which in addition could use e.g. rsync to move the distribution files to the intended static file server:

bash
make deploy

This hypothetical deploy step will likely require credentials for write access to the server.