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
Browser |
Chrome or Safari (latest versions) |
You should also be able to use INCEpTION with other browsers such as Firefox, Brave, etc. However, those are less regularly tested by the developers. It is recommended to always use the latest version of any browser product you may be using to ensure best compatibility.
Operating System |
Linux (64bit), macOS (64bit), Windows (64bit) |
Java Runtime Environment |
version 17 or higher |
The examples in this guide are based on a recent Debian Linux. Most of them should apply quite directly to Debian-based distributions like e.g. Ubuntu. INCEpTION will run on other distributions as well, but you may have to use different commands for managing users, installing software, etc.
Operating System |
Linux (64bit), macOS (64bit), Windows (64bit) |
Java Runtime Environment |
version 17 or higher |
MariaDB Server (or compatible) |
MariaDB version 10.6 or higher |
You may be able to run INCEpTION on older database server versions but it may require extra configuration that is not included in this documentation. You may consider referring to older versions of this administrators guide included with older versions of INCEpTION.
Docker |
version 24 or higher (arm64 or amd64) |
Install Java
If you aim for a Docker-based deployment, it is useful for you to read the following sections to better understand how the overall setup works. However, you will not have to install Java. If you use Docker Compose, you may also not have to install a database. Refer to the Running via Docker section instead. |
You can install a Java 17 JDK using the following commands.
$ apt update
$ apt install openjdk-17-jdk
Alternative, you can install a more recent Java version e.g. from Adoptium.
$ * apt update
$ apt install gpg
$ wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | gpg --dearmor | tee /etc/apt/trusted.gpg.d/adoptium.gpg > /dev/null
$ echo "deb https://packages.adoptium.net/artifactory/deb $(awk -F= '/^VERSION_CODENAME/{print$2}' /etc/os-release) main" | tee /etc/apt/sources.list.d/adoptium.list
$ apt update
$ apt install temurin-21-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. By default, this is a (hidden) folder called .inception
in
the home directory of the user running INCEpTION. However, you can override the location of the
home folder using the system property inception.home
.
$ java -Dinception.home="/srv/inception" -jar inception-app-webapp-33.5-standalone.jar
If you want to use a settings.properties
file, you need to place it into the INCEpTION home folder yourself.
While the home folder is automatically created if it does not exist, the settings.properties
is not
automatically created by the application.
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
-
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.
Prepare database
-
Install MariaDB
$ apt install mariadb-server
-
When setting up your database make sure your MariaDB server is configured for 4-byte UTF-8 character set and (
utf8mb4
) and a case sensitive collation (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
, you should find several.Case-sensitive vs insensitive collation (
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 calledMY PROEJCT
and the other being calledmy 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-sensitiveutf8mb4_bin
for the database.Check that the character set and collation are configured properly (in particular the items marked with a
*
in the following table).$ mariadb -u root -p MariaDB> SHOW VARIABLES WHERE Variable_name LIKE 'character\_set\_%' OR Variable_name IN ('collation_database', 'collation_server'); +--------------------------+-------------+ | Variable_name | Value | +--------------------------+-------------+ | character_set_client | utf8mb4 | * | character_set_connection | utf8mb4 | | character_set_database | utf8mb4 | * | character_set_filesystem | binary | | character_set_results | utf8mb4 | | character_set_server | utf8mb4 | * | character_set_system | utf8mb3 | | collation_database | utf8mb4_bin | * | collation_server | utf8mb4_bin | * +--------------------------+-------------+
If your settings differ, add following lines to your MariaDB config files (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
-
now set up the
inception
database. First login to MariaDB$ mariadb -u root -p
-
create a database
MariaDB> CREATE DATABASE inception DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_bin;
-
create a database user called
inception
with the passwordt0t4llYSecreT
which is later used by the application to access the database (instructions for thesettings.properties
file in the Home Folder section).MariaDB> CREATE USER 'inception'@'localhost' IDENTIFIED BY 't0t4llYSecreT'; MariaDB> GRANT ALL PRIVILEGES ON inception.* TO 'inception'@'localhost'; MariaDB> FLUSH PRIVILEGES;
For production use, make sure you choose a different, secret, and secure password. |
Older MariaDB versions
Depending on the MariaDB version you are running, you might have to make additional settings. You can check these settings using the following command.
$ mariadb -u root -p
MariaDB> * SHOW VARIABLES WHERE Variable_name IN ('innodb_large_prefix', 'innodb_file_format', 'innodb_file_per_table', 'innodb_strict_mode', 'innodb_default_row_format');
Depending on the result, you may have to add these settings to your MariaDB configuration files (cf. InnoDB System Variables):
[mysqld]
innodb_large_prefix=true # Removed in MariaDB 10.6.0
innodb_file_format=barracuda # Removed in MariaDB 10.6.0
innodb_file_per_table=1 # Deprecated in MariaDB 11.0.1
innodb_strict_mode=1
innodb_default_row_format='dynamic'
JDBC connection 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
If use are using a non-SSL database connection 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
Connections to the database may be rejected by the database server unless a timezone is specified.
The easiest way to do this is to add the following setting to the database.url
:
serverTimezone=UTC
For proper Unicode support, ensure that the database server and database connection are configured correctly:
-
in the
settings.properties
file, make sure thatdatabase.url
includesuseUnicode=true&characterEncoding=UTF-8
MySQL
The preferred database for use with INCEpTION is MariaDB. However, MariaDB and MySQL are largely compatible and in some environments, MariaDB may not be readily available. Thus, here you can find some additonal information specific to deploying INCEpTION using a MySQL database. Note that this section does not repeat all the setup instructions from the MariaDB section - the setup please refer to the MariaDB section first. This section only describes additional items specific to MySQL.
Using the MySQL JDBC driver
INCEpTION only includes the MariaDB JDBC driver. According to the MariaDB documentation, this driver is also compatible with MySQL servers. However, additional settings may be necessary when connecting to a MySQL server.
If you want to use INCEpTION with MySQL instead of MariaDB, you may also have to explicitly define the database driver. The MariaDB driver should also work for MySQL databases, but if you use a mysql
JDBC URL (like e.g. jdbc:mysql://localhost:3306/inception
), you need to explicitly define the driver in the settings.properties
file:
database.driver=org.mariadb.jdbc.Driver
In most cases, INCEpTION can auto-configure the database dialect to use. However, in some cases, this auto-detection may fail - in particular when using MySQL. For example, when using INCEpTION with MySQL 8, it may be necessary to explicitly add a database dialect configuration to the settings.properties
file:
database.dialect=org.hibernate.dialect.MySQL8Dialect
Finally, recent versions of MySQL may need this setting to avoid schema validation to fail during startup:
spring.jpa.properties.hibernate.globally_quoted_identifiers=true
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-33.5.jar
to/srv/inception/inception.jar
. Note the change of the filename toinception.jar
. -
Create the file
/srv/inception/inception.conf
with the following contentJAVA_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 lineserver.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
towww-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 HTTPD, Nginx or Caddy 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.
The setup for INCEpTION itself is the same for Apache, Nginx and Caddy:
-
Add the following lines to
/srv/inception/settings.properties
(replacingyour.public.domain.name.com
with the public domain name of your reverse proxy):# Port INCEpTION is listening on server.port=8080 # If your reverse proxy is running on the same host as {product-name}, # you can use the next line to prevent direct access to INCEpTION from other hosts server.address=127.0.0.1 # In our examples, we run {product-name} at `your.public.domain.name.com/inception` # If you want to Run {product-name} directly under the host name without an # additional path, remove this line server.servlet.context-path=/inception # Tell {product-name} which URL your users will enter into their browsers to access it. # Make sure you have an entry with and an entry without the protocol. # If you also allow unencrypted http (not recommended) then also add a line with # the http protocol wicket.core.csrf.accepted-origins[0]=your.public.domain.name.com wicket.core.csrf.accepted-origins[1]=https://your.public.domain.name.com
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.
Check that the following lines are in your settings.properties
file (see Settings, replace the server name and URL with your own):
wicket.core.csrf.accepted-origins[0]=your.public.domain.name.com wicket.core.csrf.accepted-origins[1]=https://your.public.domain.name.com
You could disable CSRF completely, but this is obviously not the recommended approach. To disable CSRF, add wicket.core.csrf.enabled=false to the settings.properties file.
|
Apache HTTPD as reverse proxy
Make sure you have read the general instructions for running behind a reverse proxy and have configured your settings file accordingly, otherwise you will not be able to properly use INCEpTION via the reverse proxy! |
This assumes that you already have the following packages installed:
-
Apache Web Server (tested with Apache/2.4.57 on Debian)
-
mod_proxy
-
mod_proxy_http
You can enable the two modules with
$ a2enmod proxy proxy_http
and check that they are enabled with
$ apachectl -M
-
Edit
/etc/apache2/conf-available/inception.local.conf
(alternatively, you may want to configure a new virtual host for INCEpTION)ProxyPreserveHost On <Location "/inception"> RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME} RequestHeader set "X-Forwarded-SSL" expr=%{HTTPS} </Location> ProxyPass /inception http://localhost:8080/inception upgrade=websocket ProxyPassReverse /inception http://localhost:8080/inception
-
Enable the configuration with
$ a2enconf inception.local
-
Restart Apache web server
$ service apache2 restart
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.
-
Enable the Stretch backports repo if needed
-
Enable mod_ssl
$ 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
Make sure you have read the general instructions for running behind a reverse proxy and have configured your settings file accordingly, otherwise you will not be able to properly use INCEpTION via the 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.
-
Enable the Stretch backports repo if needed
-
Install Certbot preconfigured 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/ws { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; proxy_set_header Host $host; } location ^~ /inception/ { proxy_pass http://127.0.0.1:8080/inception/; proxy_redirect http://inception.example.com/ /; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $remote_addr; 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
Caddy as a reverse proxy
Make sure you have read the general instructions for running behind a reverse proxy and have configured your settings file accordingly, otherwise you will not be able to properly use INCEpTION via the reverse proxy! |
This section describes using Caddy as a web server serving as a reverse proxy for INCEpTION. It further assumes that you want to use the builting funcionality to use Let’s Encrypt as a CA for obtaining valid SSL certificates.
-
You can install caddy by following the steps in Caddy. We assume that you will use the default Systemd configuration that comes with e.g. installing Caddy via apt. Also, we assume that the host you are running Caddy on has a valid DNS entry and is reachable from the internet.
-
Verify the installation with
$ systemctl status caddy ● caddy.service - Caddy Loaded: loaded (/lib/systemd/system/caddy.service; enabled; vendor preset: enabled) Active: active (running) since Wed 2022-04-27 23:17:14 CEST; 2 weeks 5 days ago Docs: https://caddyserver.com/docs/ Main PID: 3541 (caddy) CPU: 8min 36.550s CGroup: /system.slice/caddy.service └─3541 /usr/bin/caddy run --environ --config /etc/caddy/Caddyfile
-
You can stop, start or restart Caddy with
$ systemctl stop caddy $ systemctl start caddy $ systemctl restart caddy
-
Edit the Caddyfile under
/etc/caddy/Caddyfile
and paste the following (and adjust it to your own needs):
example.com handle_path "/inception" { reverse_proxy 127.0.0.1:8080 }
After you restart the Caddy service, you now have a running reverse proxy with automatic HTTPS certificates!
Running via Docker
Quick start
If you have Docker installed, you can run INCEpTION using
$ docker run -it --name inception -p8080:8080 ghcr.io/inception-project/inception:33.5
The command downloads INCEpTION from GitHub 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 ghcr.io/inception-project/inception:33.5
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 ghcr.io/inception-project/inception:33.5
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.
Memory and other Java options
By default, INCEpTION will use 80% of the memory allocated to the container. However, if you allocate very little or very much memory to the container, you may want to adjust this.
For example, to set the available memory (RAM) to e.g. 4GB, append -Xmx4g
.
$ docker run -it -e JAVA_MEM_OPTS=-Xmx4g ghcr.io/inception-project/inception:33.5
Be sure to leave some memory for the operating system inside the Docker container as well. Instead of setting a fixed value for the memory, you might consider allocating a percentage of the container’s memory to INCEpTION using -XX:MaxRAMPercentage=80
.
$ docker run -it -e JAVA_MEM_OPTS=-XX:MaxRAMPercentage=80 ghcr.io/inception-project/inception:33.5
The applications logs the amount of memory it will use during startup. Check this value to validate that your memory setting takes effect.
INFO [main] [SYSTEM] boot - Max. application memory: 4096MB
You also pass additional options to the Java runtime through the JAVA_OPTS
environment variable. This also includes system properties, e.g. -DpropertName=value
. Most of the settings that can be configured in the settings.properties
file can also be supplied in this way instead.
Customizing UID/GID
By default, INCEpTION runs with the UID 2000 and the GID 2000. On startup, any files belonging to INCEpTION are automatically reassigned to these UID/GID, in the Docker container itself as well as in any volume potentially mounted under /export
within the container. If you need the application to run as a different UID/GID, you can override these values when starting the container using the APP_UID
and APP_GID
environment variables.
$ docker run -it -e APP_UID=1234 -e APP_GID=4321 ghcr.io/inception-project/inception:{revnumber}
If the container is already started using a non-root UID, then APP_UID and APP_GID have no effect and also
no changes to the file ownerships in /export will be performed. This is e.g. the case when running a container using
-u parameter or using the Kubernetes runAsUser setting.
|
Application arguments
If it becomes necessary to pass command line arguments to INCEpTION running in Docker, this can be done using the
APP_ARGS
environment variable. Note, this is specifically for application parameters, not for parameters for the Java
Virtual Machine.
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 up [-d]
# docker-compose down
##
version: '2.4'
networks:
inception-net:
services:
db:
image: "mariadb:11.4"
environment:
- MARIADB_RANDOM_ROOT_PASSWORD=yes
- MARIADB_DATABASE=inception
- MARIADB_USER=${DBUSER:-inception}
- MARIADB_PASSWORD=${DBPASSWORD:-inception}
- MARIADB_AUTO_UPGRADE=1
volumes:
- ${INCEPTION_DB_HOME:-db-data}:/var/lib/mysql
command: ["--character-set-server=utf8mb4", "--collation-server=utf8mb4_bin"]
healthcheck:
test: ["CMD", "mariadb-admin" ,"ping", "-h", "localhost", "-p${DBPASSWORD:-inception}", "-u${DBUSER:-inception}"]
interval: 20s
timeout: 10s
retries: 10
networks:
inception-net:
app:
image: "${INCEPTION_IMAGE:-ghcr.io/inception-project/inception}:${INCEPTION_VERSION:-33.5}"
ports:
- "${INCEPTION_PORT:-8080}:8080"
environment:
- INCEPTION_DB_DIALECT=org.hibernate.dialect.MariaDB106Dialect
- 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}
volumes:
- ${INCEPTION_HOME:-app-data}:/export
depends_on:
db:
condition: service_healthy
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.
Upgrading with Docker Compose
When new versions of INCEpTION are released, they may at times include an updated Docker Compose example file.
Starting with INCEpTION 33.0, the MariaDB container that is configured in the example file will set the environment
variable MARIADB_AUTO_UPGRADE
to 1
to have MariaDB automatically upgrade its internal tables when encountering a database
produced with an earlier version of MariaDB (see MariaDB Environment Variables.
If you do not want this behavior, be sure to remove this settings from the compose file.
Running via Kubernetes
This is a very rough guide on how INCEpTION could be deployed using Kubernetes. If you are familiar with Kubernetes and cloud deployment, you will probably find a lot here that can be improved. Great! Best help us improving this guide by sending us your improvement suggestions through GitHub. |
The following Kubernetes file sets up INCEpTION along with a few volumes. It does currently NOT set up a database container but instead uses the built-in database which is not recommended for production environments. Also, it uses folders on the host system for volumes. It is only meant as an illustration. Be sure to adjust this to your environment and to use a proper database!
kind: PersistentVolume
apiVersion: v1
metadata:
name: inception-data-pv
labels:
type: local
spec:
storageClassName: standard
capacity:
storage: 5Gi
accessModes:
- ReadWriteOnce
hostPath:
path: "/srv/inception-kubernetes/data"
---
kind: PersistentVolume
apiVersion: v1
metadata:
name: inception-log-pv
labels:
type: local
spec:
storageClassName: standard
capacity:
storage: 5Gi
accessModes:
- ReadWriteOnce
hostPath:
path: "/srv/inception-kubernetes/data"
---
kind: PersistentVolume
apiVersion: v1
metadata:
name: inception-tmp-pv
labels:
type: local
spec:
storageClassName: standard
capacity:
storage: 5Gi
accessModes:
- ReadWriteOnce
hostPath:
path: "/srv/inception-kubernetes/data"
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: inception-data-pvc
spec:
storageClassName: standard
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: inception-tmp-pvc
spec:
storageClassName: standard
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
---
kind: PersistentVolumeClaim
apiVersion: v1
metadata:
name: inception-log-pvc
spec:
storageClassName: standard
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 5Gi
---
apiVersion: v1
kind: Service
metadata:
name: inception-svc
labels:
app: inception
spec:
type: NodePort
ports:
- protocol: TCP
port: 8080
targetPort: 8080
nodePort: 32000
selector:
app: inception
---
apiVersion: apps/v1
kind: Deployment
metadata:
name: inception
spec:
selector:
matchLabels:
app: inception
replicas: 1
template:
metadata:
labels:
app: inception
spec:
securityContext:
runAsUser: 2000
runAsGroup: 2000
fsGroup: 2000
runAsNonRoot: true
containers:
- name: inception
image: "ghcr.io/inception-project/inception-snapshots:33.5"
imagePullPolicy: Always
ports:
- containerPort: 8080
securityContext:
readOnlyRootFilesystem: true
privileged: false
volumeMounts:
- mountPath: /export
name: inception-data-pv
- mountPath: /tmp
name: inception-tmp-pv
- mountPath: /var/log
name: inception-log-pv
volumes:
- name: inception-data-pv
persistentVolumeClaim:
claimName: inception-data-pvc
- name: inception-tmp-pv
persistentVolumeClaim:
claimName: inception-tmp-pvc
- name: inception-log-pv
persistentVolumeClaim:
claimName: inception-log-pvc
To deploy an INCEpTION service copy this to a file called inception.yml
and then run it using
$ kubectl create -f inception.yml
To delete the service again, use
$ kubectl delete -f inception.yml
This can be tested e.g. using the Kubernetes support built into recent Docker Desktop. If you experience problems, make sure you run the latest version of Docker Desktop.
Common issues and solution
$ nginx.ingress.kubernetes.io/proxy-body-size: <value>m
example:
$ nginx.ingress.kubernetes.io/proxy-body-size: 3m
Running on Azure
This section has been compiled from community feedback. If you find that required settings are missing from this section or that any items described here are outdated or inaccurate, please help us updating the section. |
There are various options for deploying INCEpTION in the cloud. This section will not discuss all of them. Instead refer to the other sections regarding running as a JAR (on a VM), via Docker, etc.
However, depending on the cloud you are running on, there may be special considerations to take or options to set. These are described here with respect to the Microsoft Azure cloud.
Using MySQL on the Azure cloud
Please read the generic MySQL setup before reading this section. |
The default settings of MySQL instances on the Azure cloud may differ from the defauls for local installations.
Make sure that the option sql_generate_invisible_primary_key
is turned off.
Using a mounted Azure file system
Mounted file systems in the Azure clouds are known to maintain slightly inaccurate timestamps. This can in particular lead to annotators getting an error message the there have been concurrent modifications to a document and that they need to re-open the document before they can continue to annotate.
To compensate for this inaccuracy, you can use the cas-storage.file-system-timestamp-accuracy
option in your settings.properties
file.
Unsupervised installation
To perform an unsupervised installations of INCEpTION, you can:
-
set a custom password for the default
admin
account -
create the
admin
account with theROLE_REMOTE
-
enable/disable telemetry support to avoid the admin being asked on the first login
To set a custom default admin user name and password, add the following line to the settings.properties
file. If no custom user name is set, the default admin
is used.:
security.default-admin-username=mastermind
security.default-admin-password={bcrypt}XXXXXX
To obtain an encrypted password, you can use tools such as the
online bcrypt generator. Replace the XXXXXX in the example
above with the output from the tool - keep the {bcrypt}
prefix!
You could also create a user in INCEpTION, set the password you desire, and then look at the
database table users
(easiest if you are using MariaDB or MySQL).
If you want your installation to be remotely manageable directly from the outset using the admin
account, you can add the following line:
security.default-admin-remote-access=true
Mind that the remote API still needs to be enabled separately.
You can use either of the following two lines to enable or disable telemetry submission and avoid
the admin
user being asked about telemetry submission on the first login.
telemetry.auto-respond=ACCEPT
telemetry.auto-respond=REJECT
Authentication
This section describes the different authentication mechanisms supported by INCEpTION.
A user can only log in through one mechanism, either as a local user or an external user. If you are using SAML/OAuth2, then the users are bound to one particular IdP. If a user with the same name tries to log in via another mechanism or IdP, the login will be rejected. If you plan to use multiple login mechanisms or IdPs at the same time, you must ensure that the user IDs are unique across all the mechanisms and IdPs or that a given user always uses the same login mechanism. |
OAuth2 authentication
INCEpTION can authenticate a user against a OAuth2/OIDC-compatible identity provider. OAuth2/OIDC providers can be configured alongside the usual form-based login and SAML2.
It is not compatible with the external pre-authentication and does not require setting the auth.mode
property.
The following example configuration declares an OAuth2 service connection named inception-client-oauth
which uses a Keycloak instance configured for OAuth2 running at
http://localhost:8180/realms/inception-demo
. The OAuth2 support of INCEpTION should work with
any OAuth2/OIDC-compatible identity provider. For more details, please
refer to the Spring Security OAuth2 documentation.
spring.security.oauth2.client.registration.inception-client-oauth.client-name=Keycloak spring.security.oauth2.client.registration.inception-client-oauth.client-id=inception-client-oauth spring.security.oauth2.client.registration.inception-client-oauth.client-secret=ENCRYPTED_CLIENT_SECRET spring.security.oauth2.client.registration.inception-client-oauth.scope=openid, profile spring.security.oauth2.client.registration.inception-client-oauth.authorization-grant-type=authorization_code spring.security.oauth2.client.registration.inception-client-oauth.redirect-uri=http://localhost:8080/login/oauth2/code/inception-client-oauth spring.security.oauth2.client.provider.inception-client-oauth.issuer-uri=http://localhost:8180/realms/inception-demo spring.security.oauth2.client.provider.inception-client-oauth.user-name-attribute=preferred_username
The following instructions run Keycloak in development mode. This is not meant for production, only for testing. For how to properly set up a production-level Keycloak server, please refer to the official documentation of Keycloak. |
If you want to try this with a local testing instance of Keycloak, you can do this:
-
Download Keycloak
-
Run it using
./kc.sh start-dev --http-port 8180
-
Configure a new realm called
inception-demo
-
Define a new client
inception-client-oauth
and set the Valid redirection URI tohttp://localhost:8080/login/oauth2/code/inception-client-oauth
. -
Replace the
ENCRYPTED_CLIENT_SECRET
in the example configuration above with the client secret from the Credentials tab of the client in Keycloak. -
Add a new user in the Manage users area in Keycloak.
When you restart INCEpTION and access the login page now, it should offer a login option called
Keycloak. You can change the label of that option by changing the
security.oauth2.client.registration.inception-client-oauth.client-name
setting.
SAML authentication
INCEpTION can authenticate a user against a SAML2-compatible identity provider. SAML
providers can be configured alongside the usual form-based login and OAuth2.
It is not compatible with the external pre-authentication
and does not require setting the auth.mode
property.
The following example configuration declares a SAML2 service connection named inception-client-saml
which uses a Keycloak instance configured for SAML2 running at
http://localhost:8180/realms/inception-demo
. The SAML support of INCEpTION should work with
any SAML2-compatible identity provider. For more details, please
refer to the Spring Security SAML2 documentation.
spring.security.saml2.relyingparty.registration.inception-client-saml.assertingparty.entity-id=http://localhost:8180/realms/inception-demo spring.security.saml2.relyingparty.registration.inception-client-saml.assertingparty.verification.credentials[0].certificate-location=file:/srv/inception/keycloak-saml-idp.crt spring.security.saml2.relyingparty.registration.inception-client-saml.assertingparty.singlesignon.url=http://localhost:8180/realms/inception-demo/protocol/saml spring.security.saml2.relyingparty.registration.inception-client-saml.assertingparty.singlesignon.sign-request=false
The following instructions run Keycloak in development mode. This is not meant for production, only for testing. For how to properly set up a production-level Keycloak server, please refer to the official documentation of Keycloak. |
If you want to try this with a local testing instance of Keycloak, you can do this:
-
Download Keycloak
-
Run it using
./kc.sh start-dev --http-port 8180
-
Configure a new realm called
inception-demo
-
Define a new client and in the client wizard set
-
Client ID:
http://localhost:8080/saml2/service-provider-metadata/inception-client-saml
-
Client protocol:
saml
-
Save the client
-
-
Set Valid redirection URI to
http://localhost:8080/login/saml2/sso/*
. -
Set Client signature Required to
Off
-
Add a new user in the Manage users area in Keycloak.
The keycloak-saml-idp.crt
file needs to be constructed by you. Once the configuration is complete
in Keycloak, you can access http://localhost:8180/realms/inception-demo/protocol/saml/descriptor
to obtain
an XML file which contains the certificate in the ds:X509Certificate
element. You need to copy this
certificate string (usually staring with MIIC
into a text file with the following structure:
-----BEGIN CERTIFICATE----- MIIC... -----END CERTIFICATE-----
Save this file at the location indicated by the ….verification.credentials.certificate-location
key,
(here /srv/inception/keycloak-saml-idp.crt
).
When you restart INCEpTION and access the login page now, it should offer a login option called
inception-client-saml. The SAML authentication does not allow defining the provider name shown on the login page independently from the registration ID. The registration ID (here inception-client-saml
) is defined in between the registration
and assertingparty
parts of the configuration keys.
Client certificate (optional)
You can provide INCEpTION with a certificate so the IdP can verify that authentication requests are really coming from it.
-
First, we generate a certificate and a key file using (we are using a 2048-bit key here, but you might care to use a longer key)
openssl req -x509 -newkey rsa:2048 -keyout /srv/inception/inception.key -out /srv/inception/inception.crt -sha256 -days 365 -nodes -subj "/CN=inception-demo"
-
In order to upload these, both need to be in one PEM file, so we concatenate the two files:
cat /srv/inception/inception-saml.key /srv/inception/inception-saml.crt > /srv/inception/inception-saml.pem
-
Open the previously defined client in Keycloak (e.g.
http://localhost:8080/saml2/service-provider-metadata/inception-client-saml
) -
Set Client signature Required to
On
and save the settings -
Now a new tab Keys should appear at the top. Switch to it.
-
Click on Import and select PEM as the format, then upload the file
/srv/inception/inception.pem
-
Enable request signing in the
settings.properties
filespring.security.saml2.relyingparty.registration.inception-client-saml.assertingparty.singlesignon.sign-request=true
-
Configure the certificates for INCEpTION to sign its requests
spring.security.saml2.relyingparty.registration.inception-client-saml.signing.credentials[0].private-key-location=file:/srv/inception/inception-saml.key spring.security.saml2.relyingparty.registration.inception-client-saml.signing.credentials[0].certificate-location=file:/srv/inception/inception-saml.crt
Auto-login
When configuring the application for SAML/OAuth2, the user will still be required to choose an identity provider via the login page (and is also given the opportunity to log in via form-based login there).
If you would like to automatically login through a particular SAML identity provider, you
can configure this by setting the security.auto-login
property to the registration ID of the
respective provider that you configured using the spring.security.saml2.relyingparty.registration….
or spring.security.oauth2.client…
properties.
This setting is useful for single-sign-on scenarios where only a single identity provider is used.
Setting | Description | Default | Example |
---|---|---|---|
|
Auto-login using given identity provider |
<none> |
|
In case it may be necessary to bypass the auto-login, e.g. to allow signing in via credentials,
navigate to …/login.html?skipAutoLogin=true . Make sure to do this in a fresh browser session that is
not yet logged into the application.
|
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.
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 |
---|---|---|---|
|
Authentication mode |
|
|
|
Principal header |
|
some other header |
|
Default roles for new users (comma separated) |
<none> |
|
|
URL to call after logging out to also sign out of external authentication |
<none> |
|
|
Extra roles for user (comma separated) |
<none> |
|
Logging
INCEpTION comes with a default logging configuration that should serve well in a normal production environment, either on a server or running as a desktop application. However, for more advanced scenarios, it may be useful to customize the logging configuration.
Set specific log levels
Maybe you do not want to user a completely custom logging configuration and only wish to get a bit
more information in a particular part of the application. In this case, you can specify the log
level for particular packages or classes either by declaring logging properties either as system
property (-D
) argument when starting INCEpTION or by adding them to the settings.properties
file. For example, if you wanted to get more information on the authentication process, you could
use the following properties:
logging.level.org.springframework.security=TRACE
logging.level.de.tudarmstadt.ukp.inception.security=TRACE
Custom logging
A custom logging configuration can be specified when starting up INCEpTION using the parameter
-Dlogging.config=/path/to/your/log4.xml
. This should be a standard Log4J2 configuration file.
A good starting point is the default configuration used by INCEpTION which can be found in our code repository.
Logging in JSON format
If you would like to integrate the logging output of INCEpTION with something like LogStash and
Kibana, you may want log output to be in a properly interpretable JSON format, instead of the usual
plain text format. INCEpTION comes with several JSON configurations that are compatible with
popular tools like LogStash and others. You can activate it by adding the following sections to a custom log4j2.xml
file in the Appenders
sections and in the Root
logger.
<Configuration ...>
<!-- ... -->
<Appenders>
<!-- ... -->
<RollingFile name="RollingFileAppender" fileName = "logs/inception.log"
filePattern="app-%d{MM-dd-yy-HH-mm-ss}-%i.log.gz">
<JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>
<Policies>
<SizeBasedTriggeringPolicy size = "20 MB" />
</Policies>
</RollingFile>
<!-- ... -->
</Appenders>
<Loggers>
<!-- ... -->
<Root level="warn">
<!-- ... -->
<AppenderRef ref="RollingFileAppender" />
</Root>
</Loggers></Configuration>
The following bundled default configurations that are part of the log4j-layout-template-json
library
are available in INCEpTION:
-
EcsLayout.json
-
GcpLayout.json
-
GelfLayout.json
-
JsonLayout.json
-
LogstashJsonEventLayoutV1.json
-
StackTraceElementLayout.json
Monitoring
Health check
INCEpTION offers a health-checking endpoint at …/actuator/health
. It provides a JSON response indicating
whether the application is up and running.
{
"status":"UP",
"components":{
"db":{
"status":"UP",
"details":{
"database":"MariaDB",
"validationQuery":"isValid()"
}
},
"diskSpace":{
"status":"UP",
"details":{
"total": ...,
"free": ...,
"threshold": ...,
"exists":true
}
},
"ping":{
"status":"UP"
}
}
}
Metrics
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)..
|
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
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.
Sentry
In order to use Sentry as an error tracker, you will need to provide the Sentry SDK your Sentry project’s Data Source Name (DSN) and other settings in INCEpTION’s settings.properties
file. The Sentry SDK will be deactivated unless a DSN is provided.
Setting | Description | Default | Example(s) |
---|---|---|---|
|
The DSN tells the Sentry SDK where to send events. |
|
https://examplePublicKey@o0.ingest.sentry.io/0 https://examplePublicKey@sentry.your-org.com/N |
|
Set the application environment that will be sent with each event. |
production |
prod |
|
Enable transaction tracing used for performance monitoring. |
false |
true |
|
Adjust the procentage of transaction sent to Sentry. |
1.0 |
0.2 |
|
By default, the Sentry SDK do not purposefully send Personally Identifiable Information (PII) to your Sentry server. |
off |
on |
By default, only unhandled exceptions are sent to Sentry. This behavior can be tuned through configuring the sentry.exception-resolver-order
property. For example, setting it to -2147483647
(the value of org.springframework.core.Ordered#HIGHEST_PRECEDENCE
) ensures exceptions that have been handled by exception resolvers with higher order are sent to Sentry - including ones handled by @ExceptionHandler
annotated methods.
More option that can be overwritten are listed in the official Sentry SDK ducumentation.
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
Upgrade paths
There are in principle three ways to upgrade INCEpTION to a new version:
-
In-place update - in this scenario, you simply stop the application, replace the existing INCEpTION JAR file with the new version, and then start the application again. The benefit of this approach is, that is is very fast. The downside is, that in case anything goes wrong, you cannot simply go back to using the old version. You need to make sure that you have a proper backup of the application home folder and the database (if you use an external database) because the in-place update might migrate your data and after you might no longer be able to use it with an older version (e.g. if you replace the JAR again with an older version). The steps for performing an in-place upgrade are specifed in the respective section below.
-
Migrating to a fresh installation - in this scenario, you would set up a fresh installation of the new INCEpTION version using a different application home folder and a different database than your existing installation. After that, you would move the data of the old installation over to the new installation, e.g. by copying the contents of the old application home/database over into the new ones. When you start the fresh installation then, it will find the data you just copied over, automatically perform a database migration if there were any changes in the database schema, and then start up. The benefit of this approach is that in case anything does wrong during the upgrade or in case there is a critical problem with the new version, you can always go back to using the old installation and e.g. retry the update again at a later time. The steps for setting up a new instance are specified in the installation instructions. The steps for copying the data over to the new instance are the same as for performing a backup.
-
Copying projects to a fresh installation - in this scenario, you would export all projects from your existing installation. Then you would set up a new installation using a fresh application home folder/database. Finally, you would import all the exported projects into this new installation. The only situation where this type of upgrade procedure is necessary is, when you want to change the database backend, e.g. if you want to switch from an embedded database to an external database. Otherwise, there is typically no benefit in following this approach. It would only be necessary if a new INCEpTION release would completely break its database schema and not offer an automatic migration. This typically does never happen since INCEpTION has support for automatic database migrations these days. Also note that none of the user’s passwords are migrated in this way. When you import the projects in the new installation, you need to enable the import missing users option and after all projects have been imported, you need to go through each of the users, enable them, set their roles and set a new password for them. Or alternatively, you could copy the contents of the database tables
users
andauthorities
from the old database into the new one.
The release notes generally indicate that it is possible to perform an in-place upgrade of the application. However, before doing an upgrade, it is recommended 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.
Also, for certain versions there might be special considerations to be aware of when performing the upgrade. Always be sure to check the section below as well as the release notes of every version between the version you are upgrading from up to and including the version you are upgrading to.
Database upgrades
If - as recommeded - you are using a dedicated database (e.g. MariaDB), you should also occasinally upgrade that. If you are obtaining a new Docker Compose, it may well include a new database version. Please refer to the upgrade documentation of your database (e.g. MariaDB upgrade) or to the Docker Compose section in this manual for more information.
System-level backup
The system-level backup procedure is directed mainly towards server administrators. Project managers can create a project-level backup from the project settings user interface.
INCEpTION stores some data on the file system in its application home folder and other data in a database.
It is recommended to make backups while INCEpTION is not running to ensure that the data in the backup is in a consistent state.
Make sure that you can actually re-create a working installation by restoring your backup. E.g. restore your database export into a fresh database and point a new INCEpTION installation at using your application home folder copy and the restored database and then start the application and check that everything is there and working. A backup which cannot be successfully restored is worthless. |
File system backup
To create a backup your INCEpTION application home folder you can just copy the folder to another location or create a ZIP archive from it.
This backup will contain amongst other things the actual annotated data.
To keep downtime low while you are preparing the backup, consider using a copy tool that supports incremental updates such as rsync.
Database backups
If you are not using an external database, INCEpTION is using an embedded database that stores its data in the application home folder. In this case, maintaining a backup of that folder is sufficient and you can skip this section. However, if you are using an external database like MariaDB, it is essential to also maintain backups of that database! |
If you are using an external database like MariaDB, make a backup of your INCEpTION database, e.g. using the mariadb-dump command.
This backup will contain infomation about projects, documents, users, and all other structured metadata maintained by INCEpTION. It will not contain the actual annotated data which is stored on the file system!
Assuming you set up the database according to the instructions in this manual, you can use mariadb-dump
to create a backup like this:
$ mariadb-dump inception > inception-backup.sql
Restoring the backup is similary. Please make sure that the database into which you restore the backup has been set up according to the instructions in this manual. This is particularly important if you restore the database to a new system.
$ mariadb inception < inception-backup.sql
Performing an in-place upgrade
-
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
Upgrade notes
This section summarizes important upgrade notes from the release history of INCEpTION. If you upgrade from any version X
, carefully read all the upgrade notes for versions later than X
. In particular, if any of the upgrade notes mentions that an intermediate upgrade to that version must be made before going to a higher version, then first perform all required intermediate upgrades in order.
It is a good idea to back up your installation and data before an upgrade. Also make sure that you can actually re-create a working installation by restoring your backup. A backup which cannot be successfully restored is worthless. |
INCEpTION 33.0
MariaDB upgrade in the Docker Compose file
The MariaDB container that is configured in the example file will now set the environment
variable MARIADB_AUTO_UPGRADE
to 1
to have MariaDB automatically upgrade its internal tables when encountering a database
produced with an earlier version of MariaDB (see MariaDB Environment Variables.
If you do not want this behavior, be sure to remove this settings from the compose file.
The MariaDB container is also upgraded to the current LTS version 11.4 in the compose file. If you are not using the auto-upgrade behavior mentioned above, you need to manually perform the MariaDB upgrade procedure.
INCEpTION 32.0
If you are using Docker and override the memory usage of INCEpTION via the JAVA_OPTS
environment
variable, then you should remove the memory settings from that variable an instead add them to JAVA_MEM_OPTS
to ensure that you actually override the default memory settings provided by INCEpTION.
INCEpTION 25.0
Manual intervention for external pre-authentication users
If you use the external pre-authentication feature of INCEpTION (i.e. if you run it behind an
authenticating reverse proxy), you need to perform a manual maintenance step. As of this version,
all users that are created via external pre-authentication are added to the realm preauth
. Any
existing users that were created via pre-authentication need to be moved to this realm manually,
otherwise they will not be able to log in anymore.
This migration can be performed by invoking INCEpTION from the command line as:
java -jar inception-app-webapp-33.5-standalone.jar users migrate-preauthenticated-users --dry-run
This command only works if INCEpTION is configured for external pre-authentication. If you keep
the settings.properties
file in a non-standard location, you need to specify the the respective
path using -Dinception.home=/PATH/TO/FOLDER_CONTAINING_SETTINGS_PROPERTIES
before the -jar
in the
command.
The command will migrate all users that have no password (i.e. the password
in the database is
null
or an empty encrypted password was stored) and which do also not have ROLE_REMOTE
. A user
with no password cannot log in via the login form. The remote API does not support external
pre-authentication and always uses the database for authentication. So if the user either has a
password or ROLE_REMOTE
, it will not be migrated.
The command as shown above will operate in dry-run mode and will only print the results of the
migration without actually performing it. You should look at the results to see if you are ok with
them. Then, remove the --dry-run
argument and run the command again to actually perform the
migration.
The alternative to using this command is to directly update the respective user records in the
users
table in the database by setting the realm
of all externally pre-authenticated users to
preauth
.
Configuration property names changed
The following configuration property names from the settings.properties
file have changed. When you
start INCEpTION, warnings will be logged if the old names are used until you rename the
respective properties in your settings.properties
file. In a future version, the old names will
not be supported anymore and the warnings will be removed.
Old name | New name | Description |
---|---|---|
|
|
Custom message to appear on the login page. |
|
|
Maximum number of concurrently logged-in users. |
INCEpTION 24.0
PDF editor
This version includes a new PDF editor and a new PDF format. The old PDF editor and PDF format still exist, but have been renamed to PDF (legacy). When starting new projects, these old formats should no longer be used as they have known and unfixable bugs. The new PDF format that is simply called PDF is much more robust.
Compression
This version has the ability to compress CAS files on disk. This feature is turned on by default.
If you experience problems and have the feeling that they might be caused by the compression feature,
you can turn it off by adding cas-storage.compressed-cas-serialization=false
to the settings.properties
.
The compression typically reduces the size of the CAS file down to around 60% of its actual size.
The compression algorithm being used is Snappy. On many platforms, a native implementation is used automatically. If no native implementation is available, a pure-java implementation is used. Due to the reduced size, saving a CAS will take consume less I/O bandwidth which typically the overall time required to persist a CAS to storage despite the additional overhead of compression.
The compression setting takes effect whenever a CAS is written to disk. Changing it does not immediately (de)compress existing CAS files. Instead, they will be slowly converted to being (de)compressed over time as they are updated by the system as part of normal operations.
Decompressing CAS files is supported starting with INCEpTION 23.9. If you have compressed CAS files, you cannot downgrade to an older version than 23.9. Also, you cannot import projects containing compressed CAS files into versions older than 23.9.
Full-text indices
This version includes a new version of Apache Lucene which is used for maintaining the full text indices used for searching in knowledge bases and also used by the annotation search sidebar.
The indices of the knowledge bases should continue to work normally after the upgrade. If you encounter problems, you can manually trigger an index rebuild by selecting the knowledge base in the project settings and using the Rebuild index button. Note that rebuilding full text indices only works for local knowledge bases.
The indices used by the annotation search sidebar will not function until they are rebuilt. The system will automatically trigger the rebuild process when the annotation page is used. However, in particular for large projects, rebuilding the indices can take very long.
For installations with many or large projects, it is recommended to perform an offline index rebuild. First ensure that INCEpTION is not running. Then run INCEpTION from the command line as follows:
$ java -jar inception-app-webapp-24.0-standalone.jar search reindex
This command will rebuild the annotation search indices of all projects which depending on the number of projects and their size can add up to several hours (although for most people, it should be pretty fast). When the process is complete, you can restart INCEpTION as usual. Do not try to start INCEpTION while the process is still running.
INCEpTION 22.0
This version brings a new project export page which uses WebSocket. If INCEpTION is deployed behind a reverse proxy, this technical changes requires updating the reverse proxy configuration. The admin guide includes an updated section on deploying behind nginx and Apache HTTPD reverse proxies. Additionally, the CSRF settings in the INCEpTION settings.properties
file need to be updated. The required settings are also described in the admin guide in the section for deploying behind a reverse proxy.
If you have trouble reconfiguring your reverse proxy for WebSocket, it is still possible to switch back to the old export page by adding the following line to the settings.properties
file:
dashboard.legacy-export=true
The setting to switch back to the old export page will be removed in later versions. Also, INCEpTION will make more use of the WebSocket protocol in the future. If you have trouble updating your reverse proxy configuration to support WebSocket, please let us know. |
INCEpTION 21.0.1
If you are using MySQL or MariaDB, please ensure that default row format is set to dynamic
, otherwise, you may get an error like this during upgrade:
Error creating bean with name 'liquibase' defined in class path resource [org/springframework/boot/autoconfigure/liquibase/LiquibaseAutoConfiguration$LiquibaseConfiguration.class]: Invocation of init method failed; nested exception is liquibase.exception.LiquibaseException: liquibase.exception.MigrationFailedException: Migration failed for change set de/tudarmstadt/ukp/inception/preferences/model/db-changelog.xml::20210925-1::INCEpTION Team: Reason: liquibase.exception.DatabaseException: (conn=242839) Index column size too large. The maximum column size is 767 bytes. [Failed SQL: (1709) ALTER TABLE `inception-testing`.default_project_preference ADD CONSTRAINT UK_default_project_preference_name_project UNIQUE (project, name)]
To set the default row format, you can add these settings to your MySQL/MariaDB config file and then restart the database:
innodb_strict_mode=1 innodb_default_row_format='dynamic'
If you upgrade from a version older than 20.0, please check the update notes for INCEpTION 20.0.
INCEpTION 20.0
-
🎉 New versioning. INCEpTION has come a long way and the time has come to reflect that in the version. So as of this release, we are dropping the the zero from the version!
-
⚠️ Database driver changed. The MySQL driver is no longer bundled, only the MariaDB driver is shipped. If you have manually configured a DB driver and dialect in the
settings.properties
, comment them out. In the JDBC connection string replacemysql
withmariadb
. The MariaDB driver should also work with a MySQL database. If you use Docker Compose, make sure to remove theINCEPTION_DB_DIALECT
andINCEPTION_DB_DRIVER
and update theINCEPTION_DB_URL
to start withjdbc:mariadb:
instead ofjdbc:mysql:
. For additional details, please check the section on MariaDB configuration in the admin guide. -
⚠️ Increased disk usage. Internal backup for CAS (annotation) files enabled to keep 2 backups with min 24h in between - this change increases disk usage! If you operate with low disk space, consider disabling the internal backup.
INCEpTION 0.16.0
For deployments using AJP and Apache Webserver 2.5 or higher: to use the advanced AJP secret, see the updated section on running INCEpTION behind a reverse proxy in the admin guide..
For deployments using AJP and Apache Webserver 2.4 or lower: you need to disable the AJP secret by setting server.ajp.port
(replaces tomcat.ajp.port
) and server.ajp.address
properties as described in the admin guide and also set server.ajp.secret-required=false
.
Remote API
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.
Setting | Description | Default | Example |
---|---|---|---|
|
Enable remote API |
|
|
|
Enable HTTP basic authentication |
|
|
|
Enable HTTP basic authentication |
|
|
|
Client ID used by the OAuth2 IdP (mandatory if OAuth2 is enabled) |
none |
|
|
Claim containing the username |
|
|
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 API follows the Annotation Editor Remote Operations (AERO) protocol.
The third-party Python library pycaprio can be used to facilitate accessing the remote API.
OAuth2 authentication
The remote API can be used using OAuth2 authentication. A client is expected to obtain a JWT token from an OAuth2 endpoint. INCEpTION will verify that token using the public key of the OAuth2 endpoint and if the token is valid, access is granted. It is required that the user associated with then token has been created before in INCEpTION. Contrary to OAuth2 logins to the web interface, logins to the remote API do not automatically create users.
Let’s consider you are using Keycloak as the OAuth2 provider. First, you would set up a realm in
Keycloak as described in OAuth2 authentication. Assuming you followed the example,
you would now open the inception-client
client in the clients panel of the inception-demo
realm. There, you have to enable the Service Accounts toggle and save.
In the settings.properties
file, you need to add the following settings to enable OAuth2 login to
the remote API:
remote-api.oauth2.enabled=true
remote-api.oauth2.realm=inception-demo
remote-api.oauth2.user-name-attribute=preferred_username
spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8180/realms/inception-demo
Note that you must also have configured OAuth2 authentication for logins to the web interface, otherwise the next step of creating a user will not be possible.
Enabling the Service Accounts option in Keycloak will allow obtaining a JWT token using a
client ID and client credentials. You can find these credentials in the Credentials tab of the
inception-client
client in Keycloak. The preferred username of this service user is automatically
set to inception-client-service-user
by Keycloak.
Finally, to allow the inception-client-service-user
to use the remote API, you need to create that
user in INCEpTION. Go to the user management section in INCEpTION and create a user named
inception-client-service-user
. Assign at least the roles ROLE_REMOTE
and ROLE_USER
to the new user
and set the realm to external:inception-client
.
Pycaprio does currently not support OAuth2 authentication - only HTTP basic authentication. |
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.
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
Authentication headers
If the recipient of the webhook requires an authentication header, you can configure the header and its value.
webhooks.globalHooks[0].auth-header=Bearer
webhooks.globalHooks[0].auth-header-value=MY-SECRET-TOKEN
Retries
In some cases, the recipient of a webhook notification may be temporarily unavailable. It is possible to retry the delivery of a notification several times before giving up. By default,
only one delivery attempt is made (webhooks.retry-count=0
). However, you can configure up to three additional attempts with a delay of up to 5000ms between them.
webhooks.retry-count=3
webhooks.retry-delay=5000
Events being triggered while INCEpTION is being shut down may not trigger any webhook deliveries. |
Bulk changes
When performing bulk changes of annotation states (i.e. via the workload management page), no
individual ANNOTATION_STATE
events are generated. The document and project states are re-calculated
after the bulk change and depending on whether the bulk action had any effect on them,
DOCUMENT_STATE
and/or PROJECT_STATE
events are generated.
Message examples
When a webhook is triggered, it sends a HTTP POST
request to the configured URL. The X-AERO-Notification
header indicates the topic and the body of the request is a JSON structure providing
details about the state change. The JSON in the examples below have been pretty-printed for your
convenient - the actual messages are not pretty-printed.
PROJECT_STATE
{ "timestamp": 1234567890, "projectId": 123, "projectName": "Example project", "projectPreviousState": "CURATION-IN-PROGRESS", "projectState": "ANNOTATION-IN-PROGRESS" }
DOCUMENT_STATE
{ "timestamp": 1234567890, "projectId": 123, "projectName": "Example project", "documentId": 565, "documentName": "document.txt", "documentPreviousState": "CURATION-IN-PROGRESS", "documentState": "ANNOTATION-IN-PROGRESS" }
ANNOTATION_STATE
{ "timestamp": 1234567890, "projectId": 123, "projectName": "Example project", "documentId": 565, "documentName": "document.txt", "user": "annotator1", "annotationUser": "annotator1", "annotationPreviousState": "COMPLETE", "annotationState": "COMPLETE", "annotatorAnnotationState": "IN_PROGRESS", "annotatorComment":"Test comment" }
In the ANNOTATION_STATE
message, we have two fields containing a user name: user
and annotationUser
.
Usually, these two fields will be the same. They differ if a user changes the state of a document
of another user. An example is when a curator marks the curation of a document as finished. In this
case, the curator’s username is in the field user
while the annotationUser
field has the value
CURATION_USER
.
The effective annotation state can be found in the annotationState
field. However, it can be the
case that a manager has overridden the state, e.g. because an annotator forgot to mark a document
as finished. The annotatorAnnotationState
field contains the state that was (implicitly) set by the
annotator.
The annotatorComment
field contains the comment that annotators can set when closing a document
and is typically used to report a problem with the document. Thus, it can typically be found only
when the annotatorState
is COMPLETE
(document closed as successful) or LOCKED
(document closed
as not successful).
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
Setting | Description | Default | Example |
---|---|---|---|
|
Warn about unsupported browser |
|
|
|
Custom message to appear on the login page, such as project web-site, annotation guideline link, … The message supports markdown syntax. |
unset |
|
|
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. |
|
|
|
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. |
|
|
|
Execute this command instead of the operating-systems’s default command to open the browser window when running in standalone mode. |
unset |
|
|
Whether to enable the ability to install plugins into INCEpTION (experimental). |
|
|
|
Disable display of information about operating system, Java version, etc. on the error page. While this information is useful for local users when reporting bugs, security-conscious administrators running INCEpTION as a service may want to enable hiding the details to avoid information about their system being exposed. |
|
|
Security policies
You have several options of configuring which types of usernames and passwords are accepted. Note that these values are only enforced when creating new users or updating passwords. They will not invalidate existing usernames or passwords. Length restrictions and patterns are checked independently. If either fails, the username or password is rejected.
When external pre-authentication is used, these settings are ignored. |
In addition to the restrictions imposed here, INCEpTION may impose additional restrictions. E.g. certain usernames are not allowed and certain characters are also not allowed to appear in usernames. |
Setting | Description | Default | Example |
---|---|---|---|
|
Minimum number of characters a password can have |
8 |
(max 128) |
|
Maximum number of characters a password can have |
32 |
(max 128) |
|
Minimum number of characters a username can have |
4 |
(max 128) |
|
Maximum number of characters a username can have |
64 |
(max 128) |
|
Regular expression for valid usernames |
|
|
|
Regular expression for valid passwords |
|
|
|
Whether simple space characters are permitted in usernames. Enable this option only when necessary to restore access to existing accounts in certain scenarios such as when using external authentication. Usernames with spaces may lead to problems e.g. when exporting/importing projects or documents or when constructing certain URLs. |
|
|
Database connection
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:
Setting | Description | Default | Example |
---|---|---|---|
|
JDBC connection string |
HSQLDB location in application home |
jdbc:mariadb://localhost:3306/inception?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC |
|
Database username |
sa |
user |
|
Database password |
unset |
pass |
|
Database dialect |
unset (auto detected) |
org.hibernate.dialect.MariaDB53Dialect |
|
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.
Setting | Description | Default | Example |
---|---|---|---|
|
Port on which the server listens |
|
|
|
IP address on which the server listens |
|
|
|
Port for AJP connector |
|
|
|
IP address on which the AJP connector listens |
|
|
|
Whether AJP connections require a shared secret |
|
|
|
Shared secret for AJP connections |
unset |
some secret string of your choice |
|
Whether a self-refreshing startup screen is served while the application is booting before the login screen becomes available |
|
|
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 annotation 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 certain types of crashes or bugs.
This internal backup is not a replacement for a proper backup. It affects only the annotation files - not the project data, knowledge bases, or other kinds of data. Also, the annotation data is not directly re-usable by INCEpTION without additional information that is contained in the database! |
# Delete annotation backups older than 30 days (60 * 60 * 24 * 30 = 30 days)
backup.keep.time=2592000
# At least 5 minutes must pass between two annotation backups (60 * 5 = 5 minutes)
backup.interval=300
# Keep at most 10 backups for each annotation backup
backup.keep.number=10
The internal backups are controlled through three properties:
Setting | Description | Default | Example |
---|---|---|---|
|
Time between backups (seconds) |
|
|
|
Maximum number of backups to keep |
|
|
|
Maximum age of backups to keep (seconds) |
|
|
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. Setting the interval to 0
disables the internal backups.
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.
backup.interval = 300 backup.keep.number = 10 backup.keep.time = 0
backup.interval = 300 backup.keep.number = 0 backup.keep.time = 604800
backup.interval = 300 backup.keep.number = 10 backup.keep.time = 604800
CAS storage
This section describes settings related to the storage of CAS data objects (i.e. annotations).
Setting | Description | Default | Example |
---|---|---|---|
|
Whether to compress annotation files |
|
|
|
For file systems where timestamps are not exact, this can be used to configure some leniency. This setting should be used with extreme caution. If an editor accesses an annotation file that is out-of-sync with the editor, this can lead to unexpected behavior. However, when deploying INCEpTION e.g. on certain cloud storage facilitites, the file system timestamps may not be exact down to the millisecond, this it may be helpful to configure a slight leniency here. |
|
|
The compression setting takes effect whenever a CAS is written to disk. Changing it does not immediately (de)compress existing CAS files. Instead, they will be slowly converted to being (de)compressed over time as they are updated by the system as part of normal operations.
CAS cache
To speed up interactions, INCEpTION keeps a cache annotation data in memory. This cache can be tuned using the following properties:
Setting | Description | Default | Example |
---|---|---|---|
|
Number of shared read-only CASes to keep in memory |
|
|
|
Periodic interval in which the system should check if CASes can be removed from the memory cache |
|
|
|
Time a CAS should at least remain cached in memory to avoid loading from disk |
|
|
|
Time for an exclusive action to wait for another exclusive action to finish |
|
|
Document Im-/Export
Control the importing and exporting of documents:
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!
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.header.icon… |
Icons/links to display in the page header. For details, see below. |
unset |
Project dashboard
Setting | Description | Default | Example |
---|---|---|---|
|
System roles able to access project dashboards |
|
|
To specify multiple values of the ui.dashboard.accessible-by-roles in a settings.properties
file, multiple lines need to be added like ui.dashboard.accessible-by-roles[0]=ANNOTATOR ,
ui.dashboard.accessible-by-roles[1]=CURATOR , etc.
|
Project managers can always access the project dashboard, even if they are not included in the
ui.dashboard.accessible-by-roles setting.
|
Theming
There are two options of theming INCEpTION.
The recommended approach is placing a file named theme.css
into the application home folder. If
this file is present, it is automatically loaded on all pages of the application. You can place
custom styles into the file and make them override the default styles.
There is also the option to place a file called bootstrap.css
into the application folder. If that
file is present, the built-in customized Bootstrap styles of INCEpTION are not loaded and this
file is loaded instead. For the application to work, the custom bootstrap.css
must be fully
compatible with the built-in styles. To create such a file, obtain the scss
files from the
inception-bootstrap module for the INCEpTION version that you are using, adjust
them, and use SCSS to compile them from the root bootstrap.scss
file into a customized
bootstrap.css
file.
New versions of INCEpTION may come with changes to the CSS styles being used without any special announcement. If you use theming, be sure to thoroughly review if your custom styles still work with new versions. Best keep any changes minimal. |
Setting | Description | Default | Example |
---|---|---|---|
|
Whether to enable the ability switch between light and dark mode (experimental). |
|
|
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 |
|
ui.brat.single-click-selection |
Whether to select annotations with a single click |
false |
Setting | Description | Default | Example |
---|---|---|---|
annotation.feature-support.string.combo-box-threshold |
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.auto-complete-threshold |
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.auto-complete-max-results |
When an auto-complete field is used, this determines the maximum number of items shown in the dropdown menu. |
100 |
1000 |
Setting | Description | Default | Example |
---|---|---|---|
annotation.feature-support.link.auto-complete-threshold |
If the tagset is larger than the threshold, an auto-complete field is used instead of a standard combobox. |
75 |
100 |
annotation.feature-support.link.auto-complete-max-results |
When an auto-complete field is used, this determines the maximum number of items shown in the dropdown menu. |
100 |
1000 |
PDF Editor Settings
This section describes the global settings related to the PDF annotation editor module.
Setting | Description | Default | Example |
---|---|---|---|
|
enable/disable KB support |
|
|
PDF Editor Settings (legacy)
Legacy feature. To use this functionality, you need to enable it first by adding ui.pdf-legacy.enabled=true to the settings.properties file.
|
Support for this feature will be removed in a future version. The replacement is PDF Editor Settings.
This section describes the global settings related to the legacy PDF annotation editor module.
Setting | Description | Default | Example |
---|---|---|---|
|
enable/disable KB support |
|
|
Cross-layer relations
Experimental feature. While this feature introduces a new level of flexibility, it can also interact with existing features in unexpected and untested ways. |
This section describes the global settings related to the support for cross-layer relations.
Setting | Description | Default | Example |
---|---|---|---|
|
Enable/disable cross-layer relations |
|
|
Editable Segmentation Settings
Experimental feature. Highly experimental. Expect strange things to happen if you start adding/removing/changing segmentation annotations (i.e. sentences or tokens). |
This section describes the global settings related to the support for editable segmentation annotations (i.e. sentences or tokens).
Setting | Description | Default | Example |
---|---|---|---|
|
Enable/disable editing sentences |
|
|
Document Metadata Settings
This section describes the global settings related to the document metadata annotation support.
Disabling document metadata support prevents new document metadata layers from being created, but it does not prevent the use of existing document metadata layers layers in order not to break existing projects. |
Setting | Description | Default | Example |
---|---|---|---|
documentmetadata.enabled |
Enable/disable search |
false |
true |
Concept Linking
There are several configurable parameters related to the Concept Linking functionality:
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.
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.
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.
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.
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.
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:
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.
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.
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:
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.
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.
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:
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 |
Document Repositories Settings
This section describes the global settings related to the external document repository support.
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.
Setting | Description | Default | Example |
---|---|---|---|
|
enable/disable recommender support |
|
|
|
enable/disable evaluation page |
|
|
|
enable/disable recommender sidebar on annotation page |
|
|
String Matching Recommender for Relations Settings
You can enable the String recommender for relations in your INCEpTION instance.
Setting | Description | Default | Example |
---|---|---|---|
recommender.string-matching.relation |
enable/disable String relation recommender |
false |
true |
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 |
Bulk Processing Settings
Experimental feature. |
This section describes the global settings related to the bulk processing module.
Setting | Description | Default | Example |
---|---|---|---|
|
enable/disable bulk processing |
|
|
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.
Setting | Description | Default | Example |
---|---|---|---|
sharing.invites.enabled |
enable/disable invite links |
false |
true |
sharing.invites.guests-enabled |
enable/disable guest annotators |
false |
true |
sharing.invites.invite-base-url |
base URL used to generate invite links, e.g. when running behind a reverse proxy |
unset |
🧪 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.
Setting | Description | Default | Example |
---|---|---|---|
|
enable/disable versioning |
|
|
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.
Setting | Description | Default | Example |
---|---|---|---|
websocket.enabled |
enable/disable websocket support/endpoint |
false |
true |
websocket.logged-events.enabled |
enable/disable push messages for logged events |
false |
true |
websocket.recommender-events.enabled |
enable/disable push messages for recommender events |
true |
false |