Semantic Turkey System Administrator Manual

Introduction

This manual deals with advanced features related to system customization/reconfiguration.

Since version 12, the system has undergone several architectural changes. For this reason, where necessary, we divide here instructions for post/pre version 12.

Installation Options (ST versions >= 12)

Semantic Turkey after version 12 is served through Spring Boot. Most of its configuration can be modified by editing the /config/application.yml file.

Running ST on a different port

The following entry can be decommented and modified in the /config/application.yml file

# server.port: 1979

Setting up the logging

The following lines can be modified in the /config/application.yml file for changing the position of the log file and setting up the thedshold log level for the various log writers

logging:
  file:
    name: log/semanticturkey.log
  threshold:
    console: error

The following entry can be decommented and modified in order to set the logging level for each logger

#logging.level:
  #  org.springframework.security: TRACE
  #  it.uniroma2.art.semanticturkey: DEBUG

Changing the context path for the ST service

The following lines can be modified in the /config/application.yml file for modifying the context path of the ST application

# change the following to setup the context-path for the ST application
# server.servlet.context-path: /vb

Changing the session timeout

The following lines can be added/modified in the /config/application.yml file for modifying the session timeout duration of the ST application

# change the session timeout duration
# server.servlet.session.timeout: 60m

Installation Options (ST versions < 12)

Semantic Turkey versions earlier than 12 had their extension framework based on OSGi and were hosted on the Apache Karaf.

Customizing the position of the SemanticTurkeyData folder

ST uses paths relative to the SemanticTurkeyData directory. This directory is, by default, created as a sibling of SemanticTurkey. However, its position can be changed through the following file:

karaf/etc/it.uniroma2.art.semantictyrkey.cfg

by changing the propery:
data.dir=../SemanticTurkeyData

If this setting is changed on an installation of ST which already been run for the first time (i.e. it has already created the SemanticTurkeyData directory), please delete the data directory inside the root of Semantic Turkey, as it contains the old reference to SemanticTurkeyData in its cache.

Running Karaf in Different Modes and as a Service

Semantic Turkey is deployed in an Apache Karaf container (until version 3.0: "st_server_run" batch is an identical copy of the standard "karaf" batch file used to start the Karaf server)

The Karaf manual provides a dedicated section for instructions on how to start/stop Karaf in background, without console, etc..

A further page provides information on how to integrate Karaf in the operating system service wrapper.

Running Karaf on HTTPS

Instructions for configuring Karaf for HTTPS are provided in this page of the manual.

Running Karaf on a different port

the org.ops4j.pax.web.cfg pax web configuration file specifies the port on which karaf is listening, through property org.osgi.service.http.port. The file is located in the /etc directory of the Semantic Turkey installation.

The entry is configured as in the following:

org.osgi.service.http.port=1979

Change the value accordingly to set ST listening on your port of choice

Data Management

Separate Triple Store

Semantic Turkey comes with an embedded distribution of RDF4J, which includes a couple of storage solutions: in-memory store and native store. Creating local repositories with this embedded solution is very convenient for quickly playing with the platform without any additional installation.

However, to the purpose of having full control over your data, we recommed to adopt a separate triple store and connect to it remotely.

ST requires a triple store compliant with the RDF4J client API and, in order to support the more advanced features of the system such as history and validation, compliant with the RDF4J's Sail Stack mechanism.

Current available options are:

Using history & validation: deploying the change-tracking sail component in the connected triple store

If the history or validation functionalities are required for projects connected to the separate triple store, then the component of Semantic Turkey for tracking changes in the repositories has to be deployed inside the connected store.

The component, which is implemented as a sail layer for triple stores compliant with RDF4J's Sail Stack mechanism, is available as a jar file called st-changetracking-sail-<version>.jar, deployed inside the system/it/uniroma2/art/semanticturkey/st-changetracking-sail/<version> directory of Semantic Turkey.

This jar file has to be copied inside the lib directory of the connected triple store in order to enable the history validation functionalities.

Warning for those using GraphDB: we have noticed that the loading of deployed sails on the triple store only works for the standalone version, not the os-specific installation package. Please take this into account when choosing which version of GraphDB to use

Semantic Turkey Data Directory

Semantic Turkey data directory contains all data for governance of the platform, such as user data, project metadata and system configuration.

The directory is created when ST is started for the first time as a sibling of the ST installation directory. It is named by default "SemanticTurkeyData", even though its name can be configured from within the semantic turkey installation directory.

The directory is aligned to a version of Semantic Turkey, in that the structure of its contents may evolve from version to version. Each time ST is started, it checks if the registered version of the directory is aligned with the one of the application. If ST has a newer version that the data directory that it found, ST will run update routines that will realign the data directory to its own version.

The version of the data directory is stored within the directory itself, under path: system\plugins\it.uniroma2.art.semanticturkey.settings.core.SemanticTurkeyCoreSettingsManager.

Project and Behavior Customization

Custom Forms

ST provides a way to drive the creation of customized forms for UI applications. The Custom Form page on the Vocbench site details provides in detail information on how to create these custom forms.

Custom ID/URI generation

Semantic Turkey allows for the customization of generated URIs for the resources being created while editing.

From version 0.12 of Semantic Turkey, a new powerful URI generation mechanism has been made available.

Note for developers: The custom ID generator is also a useful facility for developers writing their own services where the automatic generation of URIs is requested. See the custom ID generation section in the development manual for more information. The URI generation is now driven by a dedicated extension point, of which the customizable URI generator bundled with ST represents a single instance. If the customization facilities provided by the default URI generator are not enough, it is possible to build a new one and plug it to the system.

Rendering Engine

ST provides a way to customize the rendering of resources on the user interfaces accessing its content.

Customizing Project Properties

work in progress