Administration

Overview
Getting started
Troubleshoot

Overview

The TOP Framework consists of:

Frontend: Vue.js and Quasar based Single-Page Application (top-frontend)
Backend: Spring Boot Resource Server (top-backend)

Getting started

Follow these instructions to set up the TOP framework:

Clone this repository

 git clone https://github.com/Onto-Med/top-deployment.git
 cd top-deployment

Copy docker-compose.env.tpl and modify it as needed
```
 cp docker-compose.env.tpl docker-compose.env
```
Use Docker Compose to startup the TOP Framework services
```
 docker compose up -d
```

If you didn’t modify docker-compose.env, you can now access the framework at http://localhost in your browser.

All data will be stored in the Docker volume top-data (see declaration at the end of docker-compose.yml). Feel free to update this volume configuration (e.g., make it external or provide an absolute path on the host).

How to Upgrade

Backup your Docker volumes
Pull changes from this repository
```
 cd top-deployment
 git pull
```
Review docker-compose.env.tpl for new environment variables
Pull Docker images and recreate containers
```
 docker compose up --pull always -d
```

Use SSL

The TOP Framework uses Caddy as reverse proxy. Caddy is able to automatically generate SSL certs for you.

Do the following to enable SSL:

Add a port mapping for port 443 to docker compose service ‘caddy’

 services:
   caddy:
     # ...
     ports:
       - 80:80
       - 443:443

Modify the environment variable BASE_URL in docker-compose.env to something like: ‘https://your.domain’
Restart the docker compose stack
```
 docker compose up -d
```

Add Plugins

Plugins can be provided as JAR files (dependencies must be included too, see for example Apache Maven Assembly Plugin). You just have to place those JAR files in a directory and mount it to \plugins directory of the backend container.

services:
  backend:
    # ...
    volumes:
      - top-plugins-dir:/plugins
  volumes:
    top-plugins-dir:
      # volume settings

More information about backend plugins is available at the top-backend documentation.

Add Data Adapter Configurations

You can create data adapter configuration files and mount them into the backend container by modifying docker-compose.yml. In this example, we assume that the data source configurations reside in the ./configs folder. To make a data source available to an organization and all of its repositories, an administrator has to add the data source in the organization page via the “Manage”->”Data sources” menu. For a detailed specification of the configuration files, see Data Adapter Configuration.

services:
  backend:
    # ...
    volumes:
      - ./configs:/configs:ro

Protection with OAuth2

If you want to protect front and backend with OAuth2 authentication, you must set up a Keycloak server. Respective Keycloak containers are already included in the docker-compose.yml file (use docker compose profile “auth”, e.g.: docker compose --profile auth up -d).

You may also need to modify the configurations in docker-compose.env.tpl.

If Keycloak is run for the first time, you need to create an admin account:

docker compose exec keycloak /opt/jboss/keycloak/bin/add-user-keycloak.sh -u <USERNAME> -p <PASSWORD>
docker compose restart keycloak

After starting Keycloak, log in with admin credentials and perform the following tasks:

Create a new realm (e.g.: “top-realm”)
Create a new client for that realm (e.g.: “top-frontend”). Make sure to modify the URLs in the client configuration to match your TOP Frontend instance.

The TOP Frontend should now display a login button in the top right corner. If a visitor clicks on that button they will be redirected to the Keycloak login page. After a successful login they will be redirected back to the TOP Frontend.

Troubleshoot

java.lang.OutOfMemoryError when running queries:
Depending on the query complexity and the amount of data available in a data source, queries may require a lot of memory (RAM). You can increase the Java Runtime Environment’s maximum Java heap size with the -Xmx option.
Override the entrypoint of the backend service in the docker-compose.yml file:
```
services:
  backend:
    # set maximum heap size to 4GB
    entrypoint: java -Xmx4G -cp top-backend.jar:/plugins/* org.springframework.boot.loader.PropertiesLauncher
    # other options...
```

Data Adapter Configuration