This guide covers handling INCEpTION from an administrator’s perspective.

Installation

You can run INCEpTION on any major platform supporting Java, i.e. Linux, macOS or Windows. However, we do not provide explicit support for setting up a production-ready instance of each of these platforms.

This guide assumes Debian 9.1 (Stretch). It may also work on Ubuntu with some modifications, but we do not test this. Instructions for other Linux distributions and other platforms (i.e. macOS and Windows) likely deviate significantly.

It is further assumed that the user www-data already exists on the system and that it shall be used to run the application.

All commands assume that you are logged in as the root user.

If you cannot log in as root but have to use sudo to become root, then the recommended way to do that is using the command sudo su -.

System Requirements

Table 1. Requirements for users

Browser

Chrome or Safari

Table 2. Requirements to run the standalone version

Operating System

Linux (64bit), macOS (64bit), Windows (64bit)

Java Runtime Environment

version 11 or higher

Table 3. Requirements run the server version

Operating System

Linux (64bit), macOS (64bit), Windows (64bit)

Java Runtime Environment

version 11 or higher

Apache Tomcat (or compatible)

version 9.0 or higher (Servlet API 4.0.0)

MariaDB Server (or compatible)

version 10.5 or higher

MariaDB is an open source drop-in replacement for MySQL. So generally, you can also use MySQL instead of MariaDB. Also, as far as we know, we do not use any fancy features of MariaDB 10.5 and did in fact until recently always use MySQL 5. So you can probably also use an older version of MariaDB or MySQL…​ but why should you? Think of all the unfixed bugs and consider also upgrading your database if you do a fresh installation of INCEpTION - or use Docker.

Install Java

You can install a Java 11 JDK using the following commands.

$ apt-get update
$ apt-get install openjdk-11-jdk

Application home folder

The INCEpTION home folder is the place where INCEpTION’s configuration file settings.properties resides and where INCEpTION stores its data. The settings.properties file is not automatically created by the application and needs to be created manually in the case that settings need to be configured. Mind that if you are using a dedicated database server (recommended), then INCEpTION also stores some data in the dedicated database. This is important when you plan to perform a backup, as both the home folder and the database content need to be included in the backup.

Now, let’s go through the steps of setting up a home folder for INCEpTION and creating a configuration file instructing INCEpTION to access a dedicated database.

  • Create INCEpTION home folder. This is the directory where INCEpTION settings files and projects (documents, annotations, etc.) are stored

    $ mkdir /srv/inception
  • Create and edit /srv/inception/settings.properties to define the database connection as well as internal backup properties:

    database.url=jdbc:mariadb://localhost:3306/inception?useSSL=false&serverTimezone=UTC&useUnicode=yes&characterEncoding=UTF-8
    database.username=inception
    database.password=t0t4llYSecreT
    
    # 60 * 60 * 24 * 30 = 30 days
    backup.keep.time=2592000
    
    # 60 * 5 = 5 minutes
    backup.interval=300
    
    backup.keep.number=10
  • Fix permissions in INCEpTION home folder

    $ chown -R www-data:www-data /srv/inception

Database

INCEpTION uses a SQL database to store project and user data.

INCEpTION uses by default an embedded HSQLDB database. However, we recommend using the embedded database only for testing purposes. For production use, we recommend using a MariaDB server (or compatible). The reason for this is, that:

  • some users have reported that HSQLDB databases may become corrupt when the computer crashes (note that this could probably also happen with MariaDB, but we did so far not have any reports about this);

  • most INCEpTION developers use MariaDB (or compatible) when running INCEpTION on their servers;

  • in the past, we had cases where we described in-place upgrade procedures that required performing SQL commands to change the data model as part of the upgrade. We promise to try avoiding this in the future. However, in case we offer advice on fixing anything directly in the database, this advice will refer to a MariaDB database.

We try to keep the data model simple, so there should be no significant requirements to the database being used. Theoretically, it should be possible to use any JDBC-compatible database after adding a corresponding driver to the classpath and configuring INCEpTION to use the driver in the settings.properties file.

MariaDB

For production use of INCEpTION, it is highly recommended to use a MariaDB database. In this section, we briefly describe how to install a MariaDB server and how to prepare it for use with the application.

MariaDB is an open-source drop-in replacement for MySQL. As a matter of fact, most of the commands and configuration files still use mysql in many places - so do not be confused if you read a lot about MySQL below despite working with MariaDB.

Prepare database

  • Install MariaDB

    $ apt-get install mariadb-server
  • When first setting up your database make sure your MariaDB server is configured for 4 Byte UTF-8 (utf8mb4, utf8mb4_bin) to ensure that all unicode characters can be represented (e.g. emojis).

    Upgrading an existing database installation to 4 Byte UTF-8: Changing the character-set and collation later can lead to serious trouble, so make sure you have a backup of your database. In that case, you might also need to perform some additional migration steps. We do not provide a database migration guide here, but if you search e.g. for mariadb convert utf8 to utf8mb4 (or mysql for that matter), you should find several.
    utf8mb4_bin vs. utf8mb4_unicode_ci: If you search for UTF-8 support in MariaDB, you will generally find the recommendation to use utf8mb4_unicode_ci as the collation. This, however, is a case-insensitive collation. INCEpTION is usually case-sensitive. If you used a case-insensitive collation in the database, you could not create two projects, one being called MY PROEJCT and the other being called my project, but instead of a nice error from INCEpTION, you would get an ugly error from the database. That is why we recommend using the case-sensitive utf8mb4_bin for the database.

    Check that character-set-server, default-character-set are set to utf8mb4 and collation-server is set to utf8mb4_unicode_ci by logging into MariaDB with

    $ mysql -u root -p

    and running

    mysql> SHOW VARIABLES WHERE Variable_name LIKE 'character\_set\_%' OR Variable_name LIKE 'collation%';

    If this is not the case add the following lines to your MariaDB config file (most likely /etc/mysql/my.cnf or in /etc/mysql/mariadb.conf.d):

    [client]
    default-character-set = utf8mb4
    
    [mysql]
    default-character-set = utf8mb4
    
    [mysqld]
    character-set-client-handshake = FALSE
    character-set-server = utf8mb4
    collation-server = utf8mb4_bin
    innodb_large_prefix=true
    innodb_file_format=barracuda
    innodb_file_per_table=1
    innodb_strict_mode=1
    innodb_default_row_format='dynamic'
  • now set up the inception database. First login to MariaDB

    $ mysql -u root -p
  • create a database

    mysql> CREATE DATABASE inception DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
  • create a database user called inception with the password t0t4llYSecreT which is later used by the application to access the database (instructions for the settings.properties file in the Home Folder section).

    mysql> CREATE USER 'inception'@'localhost' IDENTIFIED BY 't0t4llYSecreT';
    mysql> GRANT ALL PRIVILEGES ON inception.* TO 'inception'@'localhost';
    mysql> FLUSH PRIVILEGES;
For production use, make sure you choose a different, secret, and secure password.

Configuration options

This section explains some settings that can be added to the database.url in the settings.properties file when using MariaDB. Settings are separated from the host name and database name with a ? character and multiple settings are separated using the & character, e.g.:

database.url=jdbc:mariadb://localhost:3306/inception?useSSL=false&serverTimezone=UTC&useUnicode=true&characterEncoding=UTF-8

To suppress the warning about non-SSL database connections with recent MySQL databases, append the following setting to the database.url:

useSSL=false

You might also need to add the following if the respective connection error occurs:

allowPublicKeyRetrieval=true

Recent MySQL drivers may refuse to work unless a database server timezone has been specified. The easiest way to do this is to add the following setting to the database.url:

serverTimezone=UTC

If you plan to use 4 Byte UTF-8 encoding for project name and tagset/tag name, make sure both of the following settings for MySQL database are configured:

  • in the settings.properties file, make sure that database.url includes

    useUnicode=true&characterEncoding=UTF-8
    If you use older versins of MariaDB or MySQL (< 8), you may have to set the following property in the settings.properties file:
    spring.datasource.hikari.connectionInitSql=SET NAMES utf8mb4 COLLATE utf8mb4_bin;
  • change the my.conf MariaDB database configuration file if necessary to use utf8mb4 as default character set and utf8mb4_bin for collation (see Preparing the database).

HSQLDB (embedded)

INCEpTION displays a warning in the user interface when an embedded database is being used. It is not recommended to used an embedded database for various reasons:

  • HSQLDB databases are known to run a risk of becoming corrupt in case of power failures which may render the application inaccessible and your data difficult to recover.

  • In very rare cases it may be necessary to fix the database content which is more inconvenient for embedded databases.

In case that you really want to run INCEpTION with an embedded database in production, you probably want to disable this warning. To do so, please add the following entry to the settings.properties file:

warnings.embeddedDatabase=false

Running via embedded Tomcat (JAR)

The INCEpTION standalone JAR with an embedded Tomcat server and can be easily set up as a UNIX service. This is the recommended way of running INCEpTION on a server.

The instructions below expect a Debian Linux system. Details may vary on other OSes and Linux distributions.

Installing as a service

To set it up as a service, you can do the following steps. For the following example, we assume that you install INCEpTION in /srv/inception:

  • Copy the standalone JAR file inception-app-standalone-21.0.1.jar to /srv/inception/inception.jar. Note the change of the filename to inception.jar.

  • Create the file /srv/inception/inception.conf with the following content

    JAVA_OPTS="-Djava.awt.headless=true -Dinception.home=/srv/inception"
  • In the previous step, you have already created the /srv/inception/settings.properties file. You may optionally configure the Tomcat port using the following line

    server.port=18080

    If you need to do additional configurations of the embedded Tomcat, best refer to the documentation of Spring Boot itself.

  • We will run INCEpTION as the user www-data. Change the owner/group of /srv/inception/inception.jar to www-data. Do NOT run INCEpTION as root.

    $ chown www-data:www-data /srv/inception/inception.jar
  • Make the JAR file executable:

    $ chmod +x /srv/inception/inception.jar
  • Create a file /etc/systemd/system/inception.service with the following content:

    [Unit]
    Description=INCEpTION
    
    [Service]
    ExecStart=/srv/inception/inception.jar
    User=www-data
    
    [Install]
    WantedBy=multi-user.target
  • Enable the INCEpTION service using

    $ systemctl enable inception
  • Start INCEpTION using

    $ systemctl start inception
  • Check the log output

    $ journalctl -u inception
  • Stop INCEpTION using

    $ systemctl stop inception
If you encounter strange errors, e.g. {status=203/EXEC} and INCEpTION starts when directly executing the jar but not via systemd, then we recommend to disable SELinux.

Loading extra Java libraries

When running an application from a fat JAR (i.e. using java -jar …​), there is no way that you can specify extra libraries for the application to load (e.g. a database driver). Therefore, INCEpTION offers a special approach that works around this limitation.

In order to have the application load additional JAR files during startup, create a folder lib in the application home folder. Place any JARs that you want to load into that folder.

To check if the loading works as expected, you can add the parameter -Dloader.debug=true when starting up INCEpTION.

Running the behind a reverse proxy (JAR)

These are optional instructions if you want to run INCEpTION behind an Apache web-server instead of accessing it directly.

These guides assumes Debian 9.1 (Stretch) as the operating system. For the optional SSL configuration, it further assumes that you want to use Let’s Encrypt as a CA for obtaining valid SSL certificates.

Apache HTTPD as reverse proxy

This assumes that you already have the following packages installed:

  • Apache Web Server

  • mod_proxy

  • mod_proxy_ajp

  • mod_ssl (optional)

You can enable the two modules with

$ a2enmod proxy proxy_ajp

and check that they are enabled with

$ apachectl -M
  • Add the following lines to /srv/inception/settings.properties (server.ajp.secret might not be supported by your server version, in this case add server.ajp.secret-required=false instead)

    server.ajp.port=18009
    server.ajp.secret=SECRET_STRING_YOU_CHOOSE
    server.ajp.address=127.0.0.1
    server.servlet.context-path=/inception
    server.use-forward-headers=true
  • Edit /etc/apache2/conf-available/inception.local.conf (alternatively, you may want to configure a new virtual host for INCEpTION)

    ProxyPreserveHost On
    
    <Proxy ajp://localhost/inception >
      Order Deny,Allow
      Deny from none
      Allow from all
    </Proxy>
    
    <Location /inception >
      ProxyPass ajp://localhost:18009/inception timeout=1200 secret="SECRET_STRING_YOU_CHOOSE"
      ProxyPassReverse http://localhost/inception
    </Location>
  • Enable the configuration with

    $ a2enconf inception.local
  • Restart Apache web server

    $ service apache2 restart
The secret option is supported e.g. in Apache HTTP 2.5 mod_proxy_ajp. If you are using a reverse proxy which does not support passing along a secret, you may set server.ajp.secret-required=false in the settings.properties file.

Obtaining a Let’s Encrypt certificate

The Certification Authority (CA) Let’s Encrypt provides free TLS/SSL certificates. These certificates allow for secure HTTPS connections on web servers. Let’s Encrypt provides the software Certbot which automates the obtaining process for Apache.

$ sudo a2enmod ssl
  • Install Certbot preconfigured for Apache

$ apt-get install python-certbot-apache -t stretch-backports
  • Obtain the certificates for your domain example.com

$ certbot --apache certonly -d example.com
  • You will be prompted to enter your e-mail address and asked to agree to the terms of service. Certificate renewal information will be sent to this e-mail. If the certification process is successful it will yield the information where your certificates can be found.

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/example.com/fullchain.pem. Your cert will
   expire on 2019-04-22. To obtain a new or tweaked version of this
   certificate in the future, simply run certbot again with the
   "certonly" option. To non-interactively renew *all* of your
   certificates, run "certbot renew"
 - Your account credentials have been saved in your Certbot
   configuration directory at /etc/letsencrypt. You should make a
   secure backup of this folder now. This configuration directory will
   also contain certificates and private keys obtained by Certbot so
   making regular backups of this folder is ideal.
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le
Certificates issued by Let’s Encrypt are valid for 90 days. You will receive an expiry notification to the e-mail address you provided during the certification process.
  • Run Certbot with the command renew to renew all certificates that are due. You can also create a cron job for this purpose. The command for renewal is

$ certbot --apache renew
  • You can simulate the certificate renewal process with the command

$ certbot --apache renew --dry-run
  • The directory /etc/letsencrypt/live/example.com/ now contains the necessary certificates to proceed

$ ls /etc/letsencrypt/live/example.com
Output:
cert.pem  chain.pem  fullchain.pem  privkey.pem

Then the configuration of the web server only needs this:

<VirtualHost *:443>
    ServerName example.com
    DocumentRoot /var/www/html
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>

<VirtualHost *:80>
    ServerName example.com
    Redirect / https://example.com/
    RewriteEngine on
    RewriteCond %{SERVER_NAME} =example.com
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

NGINX as reverse proxy

This section describes using NGINX as a web server serving as a reverse proxy for INCEpTION. It further assumes that you want to use Let’s Encrypt as a CA for obtaining valid SSL certificates.

  • You can install NGINX by typing

$ apt-get update
$ apt-get install nginx
  • Verify the installation with

$ systemctl status nginx
Output:
● nginx.service - A high-performance web server and a reverse proxy server
   Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)
   Active: active (running) since Mon 2019-01-21 14:42:01 CET; 20h ago
     Docs: man:nginx(8)
  Process: 7947 ExecStop=/sbin/start-stop-daemon --quiet --stop --retry QUIT/5 --pidfile /run/nginx.pid (code=exited, status=0/SUCCESS)
  Process: 7953 ExecStart=/usr/sbin/nginx -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
  Process: 7950 ExecStartPre=/usr/sbin/nginx -t -q -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
 Main PID: 7955 (nginx)
    Tasks: 9 (limit: 4915)
   CGroup: /system.slice/nginx.service
           ├─7955 nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
           ├─7956 nginx: worker process
  • You can stop, start or restart NGINX with

$ systemctl stop nginx

$ systemctl start nginx

$ systemctl restart nginx

Obtaining a Let’s Encrypt certificate

The Certification Authority (CA) Let’s Encrypt provides free TLS/SSL certificates. These certificates allow for secure HTTPS connections on web servers. Let’s Encrypt provides the software Certbot which automates the obtaining process for NGINX.

$ apt-get install python-certbot-nginx -t stretch-backports
  • Obtain the certificates for your domain example.com

$ certbot --nginx certonly -d example.com
  • You will be prompted to enter your e-mail address and asked to agree to the terms of service. Certificate renewal information will be sent to this e-mail. If the certification process is successful it will yield the information where your certificates can be found.

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/example.com/fullchain.pem. Your cert will
   expire on 2019-04-22. To obtain a new or tweaked version of this
   certificate in the future, simply run certbot again with the
   "certonly" option. To non-interactively renew *all* of your
   certificates, run "certbot renew"
 - Your account credentials have been saved in your Certbot
   configuration directory at /etc/letsencrypt. You should make a
   secure backup of this folder now. This configuration directory will
   also contain certificates and private keys obtained by Certbot so
   making regular backups of this folder is ideal.
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
   Donating to EFF:                    https://eff.org/donate-le
Certificates issued by Let’s Encrypt are valid for 90 days. You will receive an expiry notification to the e-mail address you provided during the certification process.
  • Run Certbot with the command renew to renew all certificates that are due. You can also create a cron job for this purpose. The command for renewal is

$ certbot --nginx renew
  • You can simulate the certificate renewal process with the command

$ certbot --nginx renew --dry-run
  • The directory /etc/letsencrypt/live/example.com/ now contains the necessary certificates to proceed

$ ls /etc/letsencrypt/live/example.com
Output:
cert.pem  chain.pem  fullchain.pem  privkey.pem

Putting it all together

By now you should have

  • INCEpTION running on port 8080

  • NGINX running with default configurations on port 80

  • your issued SSL certificates

If you are running INCEpTION on a different port than 8080, please make sure to adjust the configurations below accordingly!

We will now configure NGINX to proxy pass all traffic received at example.com/inception to our INCEpTION instance.

Create a new virtual host for your domain. Inside of /etc/nginx-sites-available/ create a new file for your domain (e.g. example.com). Paste the following contents:

# Server block for insecure http connections on port 80. Redirect to https on port 443
server {
        listen          80;
        listen          [::]:80;
        server_name     example.com;
        return          301 https://$server_name$request_uri;
}

# Server block for secure https connections
server {
        listen 443 ssl;
        listen [::]:443 ssl;
        server_name inception.example.com;

        ssl on;

        # Replace certificate paths
        ssl_certificate         /etc/letsencrypt/live/example.com/fullchain.pem;
        ssl_certificate_key     /etc/letsencrypt/live/example.com/privkey.pem;
        ssl_trusted_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

        # Modern SSL Config from
        # https://mozilla.github.io/server-side-tls/ssl-config-generator/
        ssl_protocols TLSv1.2;
        ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256';
        ssl_prefer_server_ciphers on;
        ssl_session_timeout 1d;
        ssl_session_tickets off;
        add_header Strict-Transport-Security max-age=15768000;
        ssl_stapling on;
        ssl_stapling_verify on;

        ignore_invalid_headers off; #pass through headers from INCEpTION which are considered invalid by NGINX server.

        # Change body size if needed. This defines the maximum upload size for files.
        client_max_body_size    10M;

        # Uncommend this for a redirect from example.com to example.com/inception
        #location / {
        #    return 301 https://$host/inception;
        #}

        location ^~ /inception/ {
            proxy_pass http://127.0.0.1:8080/inception/;
            proxy_redirect default;
            proxy_http_version 1.1;

            proxy_set_header   Host             $host;
            proxy_set_header   X-Real-IP        $remote_addr;
            proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
            proxy_set_header   X-Forwarded-Proto $scheme;
            proxy_max_temp_file_size 0;

            proxy_connect_timeout      180;
            proxy_send_timeout         180;
            proxy_read_timeout         180;

            proxy_temp_file_write_size 64k;

            # Required for new HTTP-based CLI
            proxy_request_buffering off;
            proxy_buffering off; # Required for HTTP-based CLI to work over SSL
            proxy_set_header Connection ""; # Clear for keepalive
    }

    # Deny access to Apache .htaccess files. They have no special meaning for NGINX and might leak sensitive information
    location ~ /\.ht {
            deny all;
    }
}

Create a symlink for the new configuration file to the folder for accessible websites:

$ ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com

Test if the NGINX configuration file works without restarting (and possibly breaking) the webserver:

$ nginx -t
Output:
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If the config works restart the webserver to enable the new site

$ service nginx restart

Tell INCEpTION that it is running behind a proxy

If you are running INCEpTION via the JAR file, edit the settings.properties file to add these settings:

server.tomcat.internal-proxies=127\.0\.[0-1]\.1
server.tomcat.remote-ip-header=x-forwarded-for
server.tomcat.accesslog.request-attributes-enabled=true
server.tomcat.protocol-header=x-forwarded-proto
server.tomcat.protocol-header-https-value=https

Restart INCEpTION

$ service inception restart

INCEpTION now knows how to interpret the proxy header fields from NGINX. With this step, everything is now set up to access INCEpTION trough a secure https connection.

CSRF protection

Depending on your situation, you may get an error message such as this when trying to use INCEpTION.

Whitelabel Error Page This application has no explicit mapping for /error, so you are seeing this as a fallback.

Fri Nov 29 14:01:15 BRT 2019 There was an unexpected error (type=Bad Request, status=400). Origin does not correspond to request

If this is the case, then CSRF protection is kicking in. What seems to work in this case is to turn off CSRF entirely by adding the following lines to your settings.properties file (see Settings):

wicket.core.csrf.enabled=false
wicket.core.csrf.no-origin-action=allow
wicket.core.csrf.conflicting-origin-action=allow
Turning off a security feature is obviously not a great solution. Better check out the documentation for the Wicket Spring Boot CSRF settings and if you figure out a better solution than the above, please get in touch with use via our issue tracker.

Running via Docker

Quick start

If you have Docker installed, you can run INCEpTION using

$ docker run -it --name inception -p8080:8080 inceptionproject/inception:21.0.1

The command downloads INCEpTION from Dockerhub and starts it on port 8080. If this port is not available on your machine, you should provide another port to the -p parameter.

The logs will be printed to the console. To stop the container, press CTRL-C.

To run the INCEpTION docker in the background use

$ docker run -d --name inception -p8080:8080 inceptionproject/inception:21.0.1

Logs are accessible by typing

$ docker logs inception
Use docker run only the first time that you run INCEpTION. If you try it a second time, Docker will complain about the name inception already being in use. If you follow Docker`s suggestion to delete the container, you will loose all your INCEpTION data. Further below, we explain how you can store your data outside the container in a folder on your host.

When you want to run INCEpTION again later, use the command

$ docker start -ai inception

or for the background mode

$ docker start inception

Storing data on the host

If you follow the quick start instructions above, INCEpTION will store all its data inside the docker container. This is normally not what you want because as soon as you delete the container, all data is gone. That means for example that you cannot easily upgrade to a new version of the INCEpTION docker image when one is released.

To store your data on your host computer, first create a folder where you want to store your data. For example, if you are on Linux, you could create a folder /srv/inception:

$ mkdir /srv/inception

When you run INCEpTION via Docker, you then mount this folder into the container:

$ docker run -it --name inception -v /srv/inception:/export -p8080:8080 inceptionproject/inception:21.0.1

Settings file

The dockerized INCEpTION expects the settings.properties file in the /export folder. Instead of injecting a custom settings.properties file into the container, it is strongly recommender to use the instructions above (Storing data on the host) to mount a folder from the host system to /export then to place the into the mounted folder settings.properties. Thus, if you follow the instructions above, the settings file would go to /srv/inception/settings.properties on the host system.

Connecting to a dedicated database

By default, INCEpTION uses an embedded SQL database to store its metadata (not the texts, annotations and knowledge bases, these are stored in files on disk). For production use, it is highly recommended to use a dedicated database server (i.e. MariaDB or compatible) instead of the embedded SQL database.

Docker Compose

Using Docker Compose, you can manage multiple related containers. This section illustrates how to use Docker Compose to jointly set up a INCEpTION container as well as a database container (i.e. this one).

The following Compose script sets these containers up.

Docker Compose script
##
# docker-compose up [-d]
# docker-compose down
##
version: '3.5'

networks:
  inception-net:

services:
  db:
    image: "mariadb:10.5"
    environment:
      - MYSQL_RANDOM_ROOT_PASSWORD=yes
      - MYSQL_DATABASE=inception
      - MYSQL_USER=${DBUSER:-inception}
      - MYSQL_PORT=3306
      - MYSQL_PASSWORD=${DBPASSWORD:-inception}
    volumes:
      - ${INCEPTION_DB_HOME:-db-data}:/var/lib/mysql
    command: ["--character-set-server=utf8mb4", "--collation-server=utf8mb4_bin"]
    healthcheck:
      test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost", "-p${DBPASSWORD:-inception}", "-u${DBUSER:-inception}"]
      interval: 20s
      timeout: 10s
      retries: 10
    networks:
      inception-net:

  app:
    image: "${INCEPTION_IMAGE:-inceptionproject/inception}:${INCEPTION_VERSION:-21.0.1}"
    ports:
      - "${INCEPTION_PORT:-8080}:8080"
    environment:
      - INCEPTION_DB_DIALECT=org.hibernate.dialect.MariaDB103Dialect 
      - INCEPTION_DB_DRIVER=org.mariadb.jdbc.Driver
      - INCEPTION_DB_URL=jdbc:mariadb://db:3306/inception?useSSL=false&useUnicode=true&characterEncoding=UTF-8
      - INCEPTION_DB_USERNAME=${DBUSER:-inception}
      - INCEPTION_DB_PASSWORD=${DBPASSWORD:-inception}
      - JAVA_OPTS=-Dspring.jpa.properties.hibernate.dialect.storage_engine=innodb
    volumes:
      - ${INCEPTION_HOME:-app-data}:/export
    depends_on:
      db:
        condition: service_healthy
    mem_limit: 1g
    memswap_limit: 1g
    restart: unless-stopped
    networks:
      inception-net:
      
volumes:
  app-data:
  db-data:

Place the script into any folder, change to that folder, and issue the following command to start the containers.

$ docker-compose -p inception up -d

This will start two docker containers: inception_db_1, and inception_app_1. You can check the logs of each by running

$ docker logs inception_db_1
$ docker logs inception_app_1

The actual name of these containers might vary. A list of running containers can be retrieved by

$ docker ps

The data of the containers will be stored in Docker volumes. If you shut the containers down and start them again later, the data will still be there - try it out!

$ docker-compose -p inception down

You can list the Docker volumes on your system using

$ docker volume ls

If you want to provide a custom settings.properties file, you can also choose to mount the data volume to your hosts file system instead of to a Docker volume by setting the INCEPTION_HOME environment variable to the path you want to store your data in and where you will also put the settings.properties file. You can also choose to override the default location for the database data by setting the INCEPTION_DB_HOME environment variable.

$ export INCEPTION_HOME=/srv/inception/app-data
$ export INCEPTION_DB_HOME=/srv/inception/db-data
$ docker-compose -f docker-compose.yml -p inception up

If you are running Docker on Linux, the data of the volumes should end up on the file system anyway in a special folder used by Docker. You can figure out which folder that is using docker volume inspect …​. However, if you are running Docker on macOS or Windows, the data is likely to live in a special virtual machine that is owned by Docker and it will not be easily accessible unless you mount the data to folders on your host.

Mind that you cannot arbitrarily switch between volume-managed and host-stored data. Choose wisely.

There is a lot more that you can do using Docker and Docker Compose. Please see the docker-compose reference for details.

Monitoring

Available metrics

We expose some metrics of the running INCEpTION instance via JMX. These are currently

  • the number of active as well as enabled users

  • the overall number of documents

  • the number of enabled recommenders

  • the number of annotation documents i.e. documents being annotated per user

To make the metrics available spring.jmx.enabled=true and monitoring.metrics.enabled=true must be set in the settings.properties file (see Application home folder on this file).

Setting up metrics exporter

To export the metrics so they can be queried by the monitoring solution Prometheus, you can e.g. use the JMX exporter as a java agent.

The JMX exporter can be run as a .jar file that should be placed together with its config.yml file next to the INCEpTION .jar file. An example config.yml file that exposes metrics from INCEpTION but not webanno brat metrics (metrics associated with brat rendering) and conforms JMX metric names to Prometheus Naming conventions is:

ssl: false
whitelistObjectNames: ["de.tudarmstadt.ukp.inception.recommendation.metrics:*",
"de.tudarmstadt.ukp.clarin.webanno.api.dao.metrics:*", "de.tudarmstadt.ukp.clarin.webanno.security.metrics:*"]
blacklistObjectNames: ["de.tudarmstadt.ukp.clarin.webanno.brat.metrics:*"]
lowercaseOutputName: true
lowercaseOutputLabelNames: true
rules:
  - pattern: 'de.tudarmstadt.ukp.inception.recommendation.metrics<name=recommendationMetricsImpl, type=RecommendationMetricsImpl><>(\w+): (\d+)'
    name: inception_$1
    value: $2
    help: "Inception metric $1"
    type: GAUGE
    attrNameSnakeCase: true

  - pattern: 'de.tudarmstadt.ukp.clarin.webanno.([\.\w]+).metrics<name=(\w+), type=(\w+)><>(\w+): (\d+)'
    name: webanno_$4
    value: $5
    help: "Inception metric $4"
    type: GAUGE
    attrNameSnakeCase: true

The following line will run the JMX exporter for the JVM that runs the inception.jar. The exporter will expose the metrics on the http-endpoint localhost:9404. Make sure to use a port, 9404 in this case, that is not open to the public (only to the local network that your Prometheus instance runs in).

java -javaagent:./jmx_prometheus_javaagent-0.13.0.jar=9404:config.yaml -jar inception.jar

The JMX exporter will also automatically expose JVM metrics in the java.lang namespace which can be used to e.g. monitor memory usage:

  • jvm_memory_bytes_used: Used bytes of a given JVM memory area.

  • jvm_memory_bytes_committed: Committed (bytes) of a given JVM memory area. This means (opposed to max memory) that this memory is available to the JVM.

and others.

Scheduling

The default schedule for pulling of Prometheus is 10s, however it is necessary to make this a longer interval to avoid overwhelming your INCEpTION instance with requests for metrics. You will need to do this in your Prometheus config file.

Upgrading

In general, it is possible to perform an in-place upgrade of the application. However, before doing an upgrade, it is recommender to create a backup of the application and data to allow coming back to a working system if case of a problem during the upgrade. Mind that the upgrade is only completed once the new version has successfully started because during startup, the application may make changes to the database schema or to the data on disk.

Backup your data

  • Make a copy of your INCEpTION home folder

  • If you are using MySQL, make a backup of your INCEpTION database, e.g. using the mysqldump command.

Upgrading with embedded Tomcat

  • Stop the INCEpTION service

  • Replace the inception.jar file with the new version

  • Ensure that the file has the right owner/group (usually www-data)

  • Start the INCEpTION service again

Remote API

INFO: To use this functionality, you need to enable it first by adding remote-api.enabled=true to the settings.properties file (see the Admin Guide).

In order to programmatically manage annotation project, a REST-like remote API is offered. This API is disabled by default. In order to enable it, add the setting remote-api.enabled=true to the settings.properties file.

Table 4. Remote API settings
Setting Description Default Example

remote-api.enabled

Enable remote API

false

true

Once the remote API is enabled, it becomes possible to assign the role ROLE_REMOTE to a user. Create a new user, e.g. remote-api via the user management page and assign at least the roles ROLE_USER and ROLE_REMOTE. Most of the actions accessible through the remote API require administrator access, so adding the ROLE_ADMIN is usually necessary as well.

Once the remote API has been enabled, it offers a convenient and self-explanatory web-based user interface under <APPLICATION_URL>/swagger-ui.html which can be accessed by any user with the role ROLE_REMOTE. Here, you can browse the different operations, their parameters, and even try them out directly via a web browser. The actual AERO remote API uses <APPLICATION_URL/api/aero/v1 as the base URL for its operations.

The third-party Python library pycaprio can be used to facilitate accessing the remote API.

Webhooks

Webhooks allow INCEpTION to notify external services about certain events. For example, an external service can be triggered when an annotator marks a document as finished or when all documents in a project have been completely curated.

Webhooks are declared in the settings.properties file. For every webhook, it is necessary to specify an URL (url) and a set of topics (topics) about with the remote service listening at the given URL is notified. If the remote service is accessible via https and the certificate is not known to the JVM running INCEpTION, the certificate verification can be disabled (verify-certificates).

The following topics are supported:

  • DOCUMENT_STATE - events related to the change of a document state such as when any user starts annotating or curating the document.

  • ANNOTATION_STATE - events related to the change of an annotation state such as when a user starts or completes the annotation of a document.

  • PROJECT_STATE - events related to the change of an entire project such as when all documents have been curated.

Example webhook configuration
webhooks.globalHooks[0].url=http://localhost:3333/
webhooks.globalHooks[0].topics[0]=DOCUMENT_STATE
webhooks.globalHooks[0].topics[1]=ANNOTATION_STATE
webhooks.globalHooks[0].topics[2]=PROJECT_STATE
webhooks.globalHooks[0].verify-certificates=false

Settings

Application settings are managed via a file called settings.properties which must reside in the application home folder. This file is optional and might need to be created first in the Application home folder. If the file does not exist, default values are assumed.

General Settings

Table 5. General settings
Setting Description Default Example

warnings.unsupportedBrowser

Warn about unsupported browser

true

false

login.message

Custom message to appear on the login page, such as project web-site, annotation guideline link, …​ The message can be an HTML content.

unset

<span style="color:red; font-size: 200%;">Use are your own risk.</span>

user.profile.accessible

Whether regular users can access their own profile to change their password and other profile information. This setting has no effect when running in pre-authentication mode.

false

true

user-selection.hideUsers

Whether the list of users show in the users tab of the project settings is restricted. If this setting is enable, the full name of a user has to be entered into the input field before the user can be added. If this setting is disabled, it is possible to see all enabled users and to add any of them to the project.

false

true

commands.open-browser

Execute this command instead of the operating-systems’s default command to open the browser window when running in standalone mode. %u is replaced with the INCEpTION URL.

unset

/usr/bin/open %u -a "/Applications/Google Chrome.app"

plugins.enabled

Whether to enable the ability to install plugins into INCEpTION

false

true

Database connection

Table 6. Database settings in the settings.properties file
Setting Description Default Example

database.url

JDBC connection string

HSQLDB location in application home

jdbc:mariadb://localhost:3306/inception?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC

database.username

Database username

sa

user

database.password

Database password

unset

pass

database.dialect

Database dialect

unset (auto detected)

org.hibernate.dialect.MariaDB53Dialect

database.driver

Database driver

unset (auto detected)

org.mariadb.jdbc.Driver

database.initial-pool-size

Initial database connection pool size

4

database.min-pool-size

Minimum database connection pool size

4

database.max-pool-size

Maximum database connection pool size

10

warnings.embeddedDatabase

Warn about using an embedded database

true

false

The basic database connection details can also be configured via environment variables. When these environment variables are present, they are preferred over the settings.properties file. The following environment variables can be used:

Table 7. Database configuration via environment variables
Setting Description Default Example

INCEPTION_DB_URL

JDBC connection string

HSQLDB location in application home

jdbc:mariadb://localhost:3306/inception?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC

INCEPTION_DB_USERNAME

Database username

sa

user

INCEPTION_DB_PASSWORD

Database password

unset

pass

INCEPTION_DB_DIALECT

Database dialect

unset (auto detected)

org.hibernate.dialect.MariaDB53Dialect

INCEPTION_DB_DRIVER

Database driver

unset (auto detected)

org.mariadb.jdbc.Driver

Server Settings

These settings relate to the embedded web server in the JAR version of INCEpTION.

Table 8. Server settings
Setting Description Default Example

server.port

Port on which the server listens

8080

18080

server.address

IP address on which the server listens

0.0.0.0

127.0.0.1

server.ajp.port

Port for AJP connector

-1 (disabled)

8009

server.ajp.address

IP address on which the AJP connector listens

127.0.0.1

0.0.0.0

server.ajp.secret-required

Whether AJP connections require a shared secret

true

false

server.ajp.secret

Shared secret for AJP connections

unset

some secret string of your choice

The application is based on Spring Boot and using an embedded Tomcat server. You can configure additional aspects of the embedded web server using default Spring Boot configuration settings.

Internal backup

INCEpTION stores its annotations internally in files. Whenever a user performs an action on a document, the file is updated. It is possible to configure INCEpTION to keep internal backups of these files, e.g. to safeguard against crashes or bugs.

The internal backups are controlled through three properties:

Table 9. Database settings in the settings.properties file
Setting Description Default Example

backup.interval

Time between backups (seconds)

172800 (60 * 60 * 24 = 24 hours)

300 (60 * 5 = 5 minutes)

backup.keep.number

Maximum number of backups to keep

2

0 (unlimited)

backup.keep.time

Maximum age of backups to keep (seconds)

0 (unlimited)

2592000 (60 * 60 * 24 * 30 = 30 days)

By default, backups are disabled (backup.interval is set to 0). Changing this properties to any positive number enables internal backups. The interval controls the minimum time between changes to a document that needs to have elapsed in order for a new backup to be created.

When backups are enabled, either or both of the properties backup.keep.number and backup.keep.time should be changed as well, because their default values will cause the backups to be stored indefinitely and they will eventually fill up the disk.

The properties backup.keep.number and backup.keep.time control how long backups are keep and the maximal number of backups to keep. These settings are effective simultaneously.

Example: Make backups every 5 minutes and keep 10 backups irrespective of age
backup.interval    = 300
backup.keep.number = 10
backup.keep.time   = 0
Example: Make backups every 5 minutes and all not older than 7 days (60 * 60 * 24 * 7 seconds)
backup.interval    = 300
backup.keep.number = 0
backup.keep.time   = 604800
Example: Make backups every 5 minutes and keep at most 10 backups that are not older than 7 days
backup.interval    = 300
backup.keep.number = 10
backup.keep.time   = 604800

CAS cache

To speed up interactions, INCEpTION keeps a cache annotation data in memory. This cache can be tuned using the following properties:

Table 10. Database settings in the settings.properties file
Setting Description Default Example

cas-storage.shared-cas-cache-size

Number of shared read-only CASes to keep in memory

10-5000 (depending on heap size)

20000

cas-storage.idle-cas-eviction-delay

Time a CAS is retained in the caches after the last access

5m

1h

cas-storage.cas-borrow-wait-timeout

Time for an exclusive action to wait for another exclusive action to finish

3m

5m

Document Im-/Export

Control the importing and exporting of documents:

Table 11. Document import/export settings in the settings.properties file
Setting Description Default Example

document-import.max-tokens

Token-count limit for imported documents

2000000

0 (no limit)

document-import.max-sentences

Sentence-count limit for imported documents

20000

0 (no limit)

Custom header icons

INCEpTION allows adding custom icons to the page header. You can declare such custom icons in the settings.properties file as shown in the example below. Each declaration begins with the prefix style.header.icon. followed by an identifier (here myOrganization and mySupport). The suffixes .linkUrl and .imageUrl indicate the URL of the target page and of the icon image respectively. Images are automatically resized via CSS. However, to keep loading times low, you should point to a reasonably small image.

The order of the icons is controlled by the ID, not by the order in the configuration file!

Example: Custom header icon
style.header.icon.myOrganization.linkUrl=http://my.org
style.header.icon.myOrganization.imageUrl=http://my.org/logo.png
style.header.icon.mySupport.linkUrl=http://my.org/support
style.header.icon.mySupport.imageUrl=http://my.org/help.png
Setting Description Default Example

style.logo

Logo image displayed in the upper-right corner

unset

path to an image file

style.header.icon…​

Icons/links to display in the page header. For details, see below.

unset

Annotation editor

Setting Description Default Example

annotation.default-preferences.auto-scroll

Whether to scroll the annotation being edited into the center of the page

true

annotation.default-preferences.page-size

The number of sentences to display per page

5

annotation.default-preferences.remember-layer

Whether "remember layer" is activated by default

false

annotation.feature-support.string.comboBoxThreshold

If the tagset is larger than the threshold, an combo-box field is used instead of a radio-choice.

6

16

annotation.feature-support.string.autoCompleteThreshold

If the tagset is larger than the threshold, an auto-complete field is used instead of a standard combobox.

75

100

annotation.feature-support.string.autoCompleteMaxResults

When an auto-complete field is used, this determines the maximum number of items shown in the dropdown menu.

100

1000

ui.brat.singleClickSelection

Whether to select annotations with a single click

false

PDF Editor Settings

This section describes the global settings related to the PDF annotation editor module.

Table 12. Knowledge base settings overview
Setting Description Default Example

ui.pdf.enabled.enabled

enable/disable KB support

true

false

External pre-authentication

INCEpTION can be used in conjunction with header-based external per-authentication. In this mode, the application looks for a special HTTP header (by default remote_user) and if that header exists, it is taken for granted that this user has been authenticated. The application will check its internal database if a user by the given name exists, otherwise it will create the user.

Pre-authentication can be enabled by setting the property auth.mode to preauth. When enabling pre-authentication mode, the default roles for new users can be controlled using the auth.preauth.newuser.roles property. The ROLE_USER is always added, even if not specified explicitly. Adding also the role ROLE_PROEJCT_CREATOR allows all auto-created users also to create their own projects.

Since the default administrator user is not created in pre-authentication, it is useful to also declare at least one user as an administrator. This is done through the property auth.user.<username>.roles where <username> must be replaced with the name of the user. The example below shows how the user Franz is given administrator permissions.

In order to log out, one can specify an URL to redirect to after the session is cleared on the side of INCEpTION.

Example: Authenticate using the remote_user header, new users can create projects, user Franz is always admin.
auth.mode                     = preauth
auth.preauth.header.principal = remote_user
auth.preauth.newuser.roles    = ROLE_PROJECT_CREATOR
auth.user.Franz.roles         = ROLE_ADMIN
The roles specified through auth.preauth.newuser.roles are saved in the database when a user logs in for the first time and can be changed after creation through the user interface.
The roles added through auth.user.<username>.roles properties are not saved in the database and cannot be edited through the user interface.
Setting Description Default Example

auth.mode

Authentication mode

database

preauth

auth.preauth.header.principal

Principal header

remote_user

some other header

auth.preauth.newuser.roles

Default roles for new users (comma separated)

<none>

ROLE_PROJECT_CREATOR

auth.preauth.logoutUrl

URL to call after logging out to also sign out of external authentication

<none>

https://your-idp.com/Shibboleth.sso/Logout

auth.user.<username>.roles

Extra roles for user (comma separated)

<none>

ROLE_ADMIN

Concept Linking

There are several configurable parameters related to the Concept Linking functionality:

Cache size

This parameter controls the size of the Candidate Cache, which stores a set of candidates for a mention. Increasing the cache size will reduce the number of queries that have to be made against the KB and therefore increase average retrieval time.

Candidate Frequency Threshold

This parameter controls after how many concepts the ranking approach should take into account by selecting the n most frequent concepts. Increasing this parameter will lead to a longer ranking time, since more candidates are considered for ranking.

Mention Context Size

This parameter declares the size k of the context, where the context is defined as the words included in a window with k words to both left and right.

Candidate Retrieval Limit

This parameter defines how many concepts should be retrieved for the Candidate Retrieval step. Increasing this parameter will lead to a longer time to retrieve candidates from the KB.

Semantic Signature Query Limit

This parameter defines how many concepts should be retrieved for the Semantic Signature of a candidate. Increasing this parameter will lead to a longer time to retrieve concepts for constructing the Semantic Signature.

Candidate Display Limit

This parameter regulates how many candidates will be displayed for a mention in the Concept Selector UI.

If no value for a parameter is specified, its default value is used. The default values are shown as examples of how the parameters can be configured below:

Table 13. Concept linking settings overview
Setting Description Default Example

inception.entity-linking.cacheSize

Cache size

1024

-

inception.entity-linking.candidateQueryLimit

Candidate Retrieval Limit

2500

-

inception.entity-linking.mentionContextSize

Mention Context Size

5

-

inception.entity-linking.candidateDisplayLimit

Candidate Display Limit

100

-

inception.entity-linking.signatureQueryLimit

Semantic Signature Query Limit

2147483647

-

Resources

In order to improve the quality of suggestions, several additional resources can be incorporated. These are to be put into the .inception/resources folder. These include:

  • properties_with_labels.txt

    • List of properties, each line containing information for one property, tab-separated

ID

Label

Description

Aliases

Data type

Count

P6

head of government

head of the executive power of this town, city, municipality, state, country, or other governmental body

government headed by, executive power headed by, president, chancellor

wikibase-item

17,592

  • property_blacklist.txt

    • A list of properties that are filtered when computing the Semantic Signature, one property ID per line, e.g. P1005, P1014

  • stopwords-en.txt

    • A list of stopwords, one stopword per line, e.g. i, me

  • wikidata_entity_freqs.map

    • Each line consists of a the ID of a concept and its frequency in the KB, tab-separated, e.g. Q4664130 409104, Q30 205747

Knowledge Base Settings

This section describes the global settings related to the knowledge base module.

Default max results

This parameter determines the default value for the maximum number of results that can be retrieved from a SPARQL query. The queries are used to retrieve concepts, statements, properties, etc. from the knowledge base. The maximum number of results can also be configured separately for each knowledge base in the project settings.

Hard max results

A hard limit for the Max results parameter.

If no value for the parameter is specified, its default value is used. The default value is shown as an example of how the parameter can be configured below:

Table 14. Knowledge base settings overview
Setting Description Default Example

knowledge-base.enabled

enable/disable KB support

true

false

knowledge-base.default-max-results

default result limit for SPARQL query

1000

10000

knowledge-base.hard-max-results

hard limit for the maximum number of results from a query

10000

5000

knowledge-base.cache-size

number of items (classes, instances and properties) to cache

100000

500000

knowledge-base.cache-expire-delay

time before items are expunged from the cache

15m

1h

knowledge-base.cache-refresh-delay

time before items are asynchronously refreshed

5m

30m

knowledge-base.render-cache-size

number of items (classes, instances and properties) to cache during rendering

10000

50000

knowledge-base.render-cache-expire-delay

time before items are expunged from the render cache

10m

1h

knowledge-base.render-cache-refresh-delay

time before items are asynchronously refreshed when rendering

1m

5m

knowledge-base.remove-orphans-on-start

whether to delete orphaned KBs on start

false

true

Disabling the knowledge base support will lead to the loss of concept linked features from documents/projects that were using them. If you wish to run the application without knowledge base support, it is strongly recommended to disable the feature immediately after the installation and not after any projects have potentially started using it.

Scheduler Settings

This section describes the global settings related to the scheduler.

Number of threads

This parameter determines the number of threads the scheduler uses. It should be less than hardware threads available on the machine that runs INCEpTION. The higher the number, the more tasks can be run in parallel.

Queue size

This parameter determines the maximum number of tasks that can be waiting in the scheduler queue. If the queue is full, then no new tasks can be scheduled until running tasks are completed.

If no value for the parameter is specified, its default value is used. The default value is shown as an example of how the parameter can be configured below:

Table 15. Scheduler settings overview
Setting Description Default Example

inception.scheduler.numberOfThreads

Number of threads that run tasks

4

8

inception.scheduler.queueSize

Maximum number of tasks waiting for execution

100

200

This section describes the global settings related to the external document repository support.

Table 16. Document repository settings overview
Setting Description Default Example

external-search.enable

Enable/disable document repository support

true

false

Recommender Settings

This section describes the global settings related to the recommender module.

Table 17. Recommender settings overview
Setting Description Default Example

recommender.enabled

enable/disable recommender support

true

false

recommender.evaluation-page.enabled

enable/disable evaluation page

true

false

String Matching Recommender for Relations Settings

You can enable the String recommender for relations in your INCEpTION instance.

Table 18. String Matching Relation Recommnder Settings
Setting Description Default Example

recommender.string-matching.relation

enable/disable String relation recommender

false

true

External Recommender Settings

Table 19. External recommender settings
Setting Description Default Example

recommender.external.enabled

enable/disable external recommender support

true

false

recommender.external.connect-timeout

duration of connect timeout

30s

3m

recommender.external.read-timeout

duration of read timeout

30s

3m

Invite Links Settings

Experimental feature.

You can enable invite links for your INCEpTION instance. This will allow project managers to generate invite links for their project which will expire automatically after one year or at a chosen date. They can also be deleted or regenerated by the manager. Any user of your instance can use this invite link to access the project. She will automatically be added to the project with annotator rights when following it.

Optionally, users can be invited using a password-less login. In this mode, the user logging in simply chooses a login name and a project-bound password-less account for this user is created. The user can only login to this account via the invite link. When the project is deleted, all the project-bound accounts are deleted as well. The project-bound accounts internally use a randomized user ID which allows projects projects with such accounts to be exported and imported into other instances.

Table 20. Invite Links settings
Setting Description Default Example

sharing.invites.enabled

enable/disable invite links

false

true

sharing.invites.guests-enabled

enable/disable guest annotators

false

true

Versioning Settings

Experimental feature.

You can enable versioning for projects in your INCEpTION instance. Project managers can create snapshots of all documents in the project as well as its layer configuration via the versioning panel. This is done via a git repository stored in the .inception folder. This git repository can also be used to push to a remote repository, e.g. saving on Github or Gitlab.

Table 21. Versioning settings
Setting Description Default Example

versioning.enabled

enable/disable versioning

false

true

Websocket Settings

Experimental feature.

You can enable websocket support for your instance which allows to push messages to the client browser. This can e.g. be information for Admin users on recently logged events.

Table 22. Websocket settings
Setting Description Default Example

websocket.enabled

enable/disable websocket support/endpoint

false

true

websocket.loggedevent.enabled

enable/disable push messages for logged events

false

true