Instructions to run AOAME locally

Summary

Docker

• Installation with Docker
• Start AOAME
• Upload Ontologies to Jena Fuseki
• Stop the Services
• Remove the Services

Local Installation (source code access)

• Local Installation
• Setup Development Environment
• Building the WebService
• Running/Debugging the WebService
• Building the WebApp
• Starting AOAME
• Pushing the artifact to GitHub and AOAME
• Troubleshooting & Known Issues

Docker

Installation with Docker

1. Download Docker Desktop from Docker's official website: https://www.docker.com/products/docker-desktop/
2. Install Docker Desktop as administrator: click Default Setup, and skip the creation of an account
3. Run Docker Desktop as administrator

Setup AOAME

• Prerequisites:
  • Docker Desktop
  • Git: https://git-scm.com/downloads
• Run the setup_local.bat (Windows) or setup_local.sh (MacOs/Linux) file
  • This script will git pull all required repositories: WebApp, WebService, JenaFuseki into aoame/ directory

Start AOAME

• Make sure Docker Desktop is running
• For Windows: Run the docker_start_local.bat file (run as administrator if access denied).
• For MacOS/Linux: Run the docker_start_local.sh file (try to run as administrator if access denied).
  • Open a terminal/console in the Project Directory
    • drag the file into the terminal or use cd path-to-the-project to navigate to the project directory if needed.
  • Make the script executable with chmod +x start_local_docker.sh and run it ./start_local_docker.sh. Mac Support
• Alternatively for any OS
  • Open a terminal in the Project Directory and run the following command:

docker compose up --build

Open your browser:

Access the WebApp at: http://localhost:4200/

Access Jena Fuseki Triple Store at: http://localhost:3030/

If any files (such as pictures, code, etc.) are modified, the affected service needs to be removed Remove the Services and rebuilt Start AOAME

Upload Ontologies to Jena Fuseki

1. Download triples from Ontology4ModelingEnvironment repository.
2. Open Jena Fuseki in your browser: http://localhost:3030/
3. Click on "dataset" tab, then click on "upload files" tab
4. Click on "Select files...", upload the downloaded triples

Stop the services

• Open Docker Desktop, go to Containers tab (the top one), click on the stop button 🟦
• Alternatively, open the running terminal and press Ctrl+C 2 times to stop the services
• Alternatively, run the following command in the terminal:

docker compose down

Remove the services

This step is important in case of any changes are made!

• Open Docker Desktop, go to Containers tab (the top one), click on the remove button
• Go to Images tab (the top one), click on the remove button

Local Installation

Prerequisites

To run AOAME locally you first need to install the following software:

• Git: https://git-scm.com/downloads

• JDK: https://adoptium.net/temurin/archive/?version=17 Make sure you install the current version of the project: Temurin 17.0.7+7

• Either IntelliJ: https://www.jetbrains.com/idea/download/ (requires academic license) or Eclipse: https://www.eclipse.org/downloads/ or only Maven: https://maven.apache.org/

• Optionally WebStorm: https://www.jetbrains.com/webstorm/ (requires academic license)

• Node.js: https://nodejs.org/en/blog/release/v16.4.2
  Important: Install the node version that is required by the WebApp project in package.json. Check it via the link: WebApp repo package.json

• Check the required node version here: "engines": { "node": "'Node_Version'" }

To make changes to the source code of the WebService it is recommended to install IntelliJ or Eclipse which comes with its own version of Maven. If you do not plan on making changes to the WebService it is also possible to install Maven on its own.

When installing Eclipse make sure to choose “Eclipse IDE for Enterprise Java and Web Developers”.

WebStorm is not needed for running AOAME locally but it can be used to make changes on the WebApp.

Setup Development Environment

To contribute to the project, set up the development environment:

• Run setup_local.bat (Windows) or setup_local.sh (MacOs/Linux) file
• This script will git pull all required repositories: WebApp, WebService, JenaFuseki into aoame/ directory

After the script has finished, you will need to build the WebService and the WebApp before they can be used.

Building the WebService

Using IntelliJ (recommended)

Start IntelliJ, open the WebService project: click File, Open, provide the path to WebService. The WebService is inside of newly created aoame folder OntologyBasedModellingEnvironment-WebService.

To build the project, click Run and Edit Configurations. Then, add the following configuration in IntelliJ and run it.

Using Eclipse

Start Eclipse and click File then Import…

Select Projects from Folder or Archive. Then click on Next.

The setup_local.bat script should have created a folder called aoame which contains a folder called OntologyBasedModellingEnvironment-WebService. Select the OntologyBasedModellingEnvironment-WebService folder by clicking Directory… and navigating to it.

After you have selected the directory click Finish.

Now you need to setup a run configuration. To do that click on the down arrow then on Run As and the on Maven build.

In the Goals field write package. Then click on Run to start the Maven build.

The next time you want to build the WebService you can run Maven by clicking on OntologyBasedModellingEnvironment-WebService inside the dropdown menu.

Using Maven directly

If you use Maven directly you can build the WebService by running mvn verify.

Running/Debugging the WebService

Using IntelliJ

Open Run configrations again, click on the + sign to add a new JAR Application.

Provide the Path to JAR according to your setup.
Enter Program arguments, as shown below.

Add Run Maven package to Before launch, right below. This will build the project before every launch.

Finally, press run or debug buttons.

Building the WebApp

Using WebStorm

First open the folder OntologyBasedModellingEnvironment-WebApp inside WebStorm. Then click on Add Configuration…

Click on the plus symbol at the top left of the dialog.

Select npm on the dropdown.

On the Scripts dropdown select build. You have now added a configuration to build the WebApp.

To start building the WebApp make sure that build is selected on the dropdown then click on the green arrow to the right of the dropdown.

You can also add a second configuration with heroku-start. This can be used to start the WebApp through WebStorm.

Using the Command line

If you do not want to use WebStorm you can use the command ng build to build the WebApp.

Starting AOAME

To start fuseki, the WebService and the WebApp at the same time you can use the start_local.bat script.

To start fuseki on its own run the fuseki-server.bat script inside the fuseki-heroku-test folder.

To start the WebService on its own run the start webserver.bat script inside the OntologyBasedModellingEnvironment-WebService folder.

To start the WebApp on its own run node server.js in a command prompt inside the OntologyBasedModellingEnvironment-WebApp folder.

Pushing the artifact to GitHub and AOAME

To push your version to GitHub follow the steps below:

1. Ensure you have access to the required repositories for your project. Depending on the scope, it might be 1-3 repos:

https://github.com/BPaaSModelling/OntologyBasedModellingEnvironment-WebApp

https://github.com/BPaaSModelling/OntologyBasedModellingEnvironment-WebService

To push a new ontology you will need access to:
https://github.com/BPaaSModelling/Ontology4ModelingEnvironment

2. Create a personal access token to push it from Intellij/WebStorm/Eclipse, unless you have another authentication method like the ssh key. Usually, the GitHub account password doesn’t work.

Open GitHub -> Settings -> Developer Settings ->Personal access tokens -> Tokens (classic) -> Create one token with default repo access -> copy the token, you will need it later.

3. Open Intellij/WebStorm/Eclipse. Go to Git -> Connect to the respective repository -> Use your token as a password when connecting.

4. Create a new branch for your version, commit all your changes, and push.

5. Now, merge your branch into the master branch.

In Intellij or WebStorm, right-click the master branch and click "checkout the master". Now, you can merge your branch into the master branch (screenshot below). Once it is done, please test that everything works as expected. If testing is successful, push the new master branch.

If you need to push to the Ontology4ModelingEnvironment repo, first you need to merge the master into your own branch.

Create a Pull request directly from GitHub that will be merged when approved (see screenshots).

Troubleshooting & Known Issues

Angular CLI requires newer Node.js

If you see:

The Angular CLI requires a minimum Node.js version of v18.19.

But you're using Angular 10 (as in this project), then the CLI version is too new.

Fix:

• Uninstall current CLI:

npm uninstall -g @angular/cli

• Install version compatible with Angular 10:

npm install --save-dev @angular/cli@10.2.3

• Then build using:

npx ng build

npm ERESOLVE error during install

Fix: Use this flag to allow older dependencies:

npm install --legacy-peer-deps

ERR_OSSL_EVP_UNSUPPORTED when using Node 17+

This OpenSSL error means Node.js is too new for Angular 10/Webpack 4.

Fix options:

1. Downgrade to Node v16.4.2
2. Or set this environment variable temporarily:

set NODE_OPTIONS=--openssl-legacy-provider
npx ng build

Java WebService error: javax.ws.rs.Path not present

Tomcat throws:

Caused by: java.lang.ClassNotFoundException: javax.ws.rs.Path

Fix: Add the following to the WebService pom.xml under <dependencies>:

<dependency>
  <groupId>javax.ws.rs</groupId>
  <artifactId>javax.ws.rs-api</artifactId>
  <version>2.1.1</version>
  <scope>provided</scope>
</dependency>

Then run:

mvn clean package

Folder "aoame" already exists

If you rerun the script and get:

A subdirectory or file aoame already exists.

You can delete the folder manually, or update the script to:

if not exist aoame mkdir aoame

Checking your environment

Use these commands to confirm you have compatible versions installed:

node -v           # should be v16.4.2
npm -v            # around 7.x
npx ng version    # check Angular version used
java -version     # should be Temurin 17.0.7+7
mvn -v            # to confirm Maven is installed