Ontology

Ontology application is an application based on Sirius-Web to manage ontologies.

This repository is a mono repo containing both frontend and backend components.

To test Ontology you have two possible options:

1. If you just want to run an already built version of the example application, follow the Quick Start.

2. If you want to build the application yourself, follow the complete Build instructions.

Quick Start

If you want a quick overview of how Ontology looks and feels like without building the sample application yourself, you will simply need:

• Java 17

• Docker, or an existing PostgreSQL 12 (or later) installation with a DB user that has admin rights on the database (those are needed by the application to create its schema on first startup).

To actually run the application:

1. Ontology uses PostgreSQL for its database. For development or local testing, the easiest way is to start a PostgreSQL instance using Docker.

   docker run -p 5437:5432 --name ontology-postgres \
                               -e POSTGRES_USER=dbuser \
                               -e POSTGRES_PASSWORD=dbpwd \
                               -e POSTGRES_DB=ontology-db \
                               -d postgres

   If you do not have Docker or want to use an existing PostgreSQL installation, adjust the command-line parameters below and make sure the DB user has admin rights on the database; they are needed to automatically create the DB schema.

2. Start the application:

   Get the ontology-application-{$version}.jar from the last successful build on Ontology github

   java -jar ontology-application-{$version}.jar \
             --spring.datasource.url=jdbc:postgresql://localhost:5437/ontology-db \
             --spring.datasource.username=dbuser \
             --spring.datasource.password=dbpwd

3. Point your browser at http://localhost:8080 and enjoy!

   Warning

   The initial version of Ontology has some known issues with Firefox. It is recommended to use a Chrome-based browser until these are fixed.

   Note	Do not forget to stop the PostgreSQL container once you are done: docker stop ontology-postgres.

Building

Requirements

To build the application yourself you will need the following tools:

• Git, and a GitHub account

• To build the backend components:

  • Java 17

  • Apache Maven 3.6.3

  • Docker must be installed and running for some of the backend components tests to run.

• To build the frontend components:

  • LTS versions of Node and NPM: in particular, Node >= 18.7.0 is required along with npm >= 8.15.0.

Warning

Note that there are issues with npm under Windows Subsystem for Linux (WSL). If you use WSL and encounter error messages like "Maximum call stack size exceeded" when running NPM, switch to plain Windows where this should work.

For Windows users: Due to the Maximum Path Length Limitation of Windows, you may exceed the limit of 260 characters in your PATH. To remove this limitation, apply the this procedure with this command line in PowerShell (New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force), then active the longpath option in Git in a command line with administrator rights (git config --system core.longpaths true).

GitHub Access Token

The backend of Ontology depends on sirius-emf-json and sirius-web, which is published as Maven artifacts in GitHub Packages. To build ontology locally, you need a GitHub Access Token so that Maven can download the artifacts.

1. Create a personal token with a scope of read:package by following the GitHub documentation if you do not have one already.

   Warning

   Once generated, a token cannot be displayed anymore, so make sure to copy it in a secure location.

2. Create or edit $HOME/.m2/settings.xml to tell Maven to use this token when accessing the Sirius EMF JSON repository:

   <?xml version="1.0" encoding="UTF-8"?>
   <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd">
     <servers>
       <server>
         <id>github-sirius-emfjson</id>
         <username>$GITHUB_USERNAME</username>
         <password>$GITHUB_ACCESS_TOKEN</password>
       </server>
       <server>
         <id>github-sirius-web</id>
         <username>$GITHUB_USERNAME</username>
         <password>$GITHUB_ACCESS_TOKEN</password>
       </server>
       <server>
         <id>github-ontology</id>
         <username>$GITHUB_USERNAME</username>
         <password>$GITHUB_ACCESS_TOKEN</password>
       </server>
     </servers>
   </settings>

   Be sure to replace $GITHUB_USERNAME with your GitHub user id, and $GITHUB_ACCESS_TOKEN with the value of your acess token done in the previous step.

   Important

   The id used in your settings.xml must be the ones mentioned above to match what is used in the POMs.

3. Create or edit $HOME/.npmrc and add the following line:

   //npm.pkg.github.com/:_authToken=$GITHUB_ACCESS_TOKEN

   Again, be sure to replace $GITHUB_ACCESS_TOKEN with the value of your access token.

Build Ontology application

Build steps:

1. Clone Ontology repository

2. Build the frontend (from the frontend subfolder of Ontology main location):

   npm ci
   npm run build

Note	In case of npm ERR! Lifecycle script format-lint failed with error, try to run from the frontend subfolder the following command: npm run format

1. Install the frontend artifacts as static resource to be served by the backend. From the root directory of the repository:

   mkdir -p backend/ontology-frontend/src/main/resources/static
   cp -R frontend/ontology-web/dist/* backend/ontology-frontend/src/main/resources/static

2. Build the backend (from the backend subfolder of Ontology main location):

   mvn clean verify

   The result is a ready-to-run, Spring Boot "fat JAR" in backend/ontology-application/target/ontology-application-<VERSION>.jar. Refer to the instructions in the "Quick Start" section above to launch it.

Development environment

Here are instructions that new Ontology developer could follow in order to set up the development environment.

Note	The set up of the Github token is required for setting up back end and front (see GitHub Access Token)

Backend set up

1. Download your preferred Java IDE

2. Clone Ontology repository

3. Import Ontology projects in workspace

4. For windows users, please set your git configuration to:

   • git config core.autocrlf true

   • git config core.eol lf

5. Set up your IDE with

   • Checkstyle configuration.

     backend/releng/resources/checkstyle/CheckstyleConfiguration.xml

   • Editor configurations

     backend/releng/resources/editor

6. Create Launch Configuration for Ontology server

   • Start the server with ontologyWeb.java class.

   • For debugging, add the following environment variable spring.profiles.active=dev

Frontend set up

1. Open the frontend folder in VSCode

2. Install dependencies using npm install in the terminal

Launch Application as a developer

1. Run database docker image (see Docker command)

2. Launch backend from your Java IDE (see Launch configuration)

3. Launch frontend npm start

License

Everything in this repository is Open Source. Except when explicitly mentioned otherwise (e.g. for some resources likes images), the license is Eclipse Public License* v 2.0.