Configuration

DBVTK Home directory

This is the directory where all the configuration files related to DBVTK are stored. It can be set via the java property dbvtk.home or the environment variable DBVTK_HOME.

By default this is <user home directory>/.dbvtk. This directory is created and populated when the server is run for the first time.

When using a non-default home directory, this is the only java property/environment variable that needs to be set, since DBVTK will fetch the remaining settings from the configuration files in this directory.

For the "easy-setup" solution, DBVTK_HOME is set to the dbvtk-data directory (which is included in the downloaded ZIP package).

Files and folders in DBVTK Home

The configuration files need to be added to the folder <DBVTK home>/config in order to be picked up by the application. The default configuration can be found at <DBVTK home>/example-config. The example configuration files can be copied to <DBVTK home>/config and changed in order to override the default options.

The configuration files are:

• config/dbvtk-viewer.properties
  • Main DBVTK configuration file
• config/logback.xml
  • Logging configuration file
• config/i18n/ServerMessages<language>.properties
  • Translations for server side messages
• config/theme/*
  • Theme customization files

Details on how to change each file is present in the following sections.

Other files present in that directory:

• log/dbvtk.log
  • Log for the Database Visualization Toolkit web application
• lobs/**
  • Large Object files from the original database. These need to be here in order for LOB downloading to work

config/logback.xml

Please refer to the logback configuration documentation to configure logging.

config/i18n/ServerMessages<language>.properties

Please read the translating page.

config/dbvtk-viewer.properties

To setup the solr endpoint to be used by DBVTK, add or change the following line:

solr.url = http://127.0.0.1:8983/solr/

The following properties are used to set up authentication and authorization.

The user and permission management is done in RODA, therefore the following instructions assume that RODA is set up and accessible. If you want to integrate the DBVTK and RODA (to support DIP creation for SIARD2 databases) you need to use the roda-dbptk-plugin.

Authentication

To authenticate using RODA you need to change the following lines:

ui.filter.internal.enabled = true
ui.filter.internal.server = http://<RODA hostname and port>

Authorization

To verify permissions to access a specific database DIP using RODA, you need to change the following line:

ui.authorization.roda.enabled = true

Admins and managers

The following properties should be set to the usernames of users who can:

• access the list of databases (admin)
• edit or remove saved searches (admin & manager)

ui.authorization.roda.users.admin = admin
ui.authorization.roda.users.admin = admin2
ui.authorization.roda.users.manager = manager
ui.authorization.roda.users.manager = manager2

in this example, users admin and admin2 that can see the list of databases; and admin, admin2, manager and manager2 can edit and remove saved searches.

Authorization Groups

The configuration follows a structured format where each authorization group is defined with specific attributes. The system determines a user’s group membership by evaluating a session attribute against a predefined value using an operator.

Parameters

• label: The name displayed in the user interface.
• attributeName: The session attribute used for comparison.
• attributeOperator: The operator used for permission validation (currently, only EQUAL is supported).
• attributeValue: The expected value required for group membership validation.

Configuration File

This configuration must be added to the dbvtk-viewer.properties file.

Example Configuration

The following example defines an authorization group named Users. This configuration checks whether the logged-in user's session attribute memberOf is equal to users:

lists.collections.authorization.groups[]=users
lists.collections.authorization.groups[].users.label=Users
lists.collections.authorization.groups[].users.attributeName=memberOf
lists.collections.authorization.groups[].users.attributeOperator=EQUAL
lists.collections.authorization.groups[].users.attributeValue=users

User Membership Example

User group membership is defined in the attribute-repository.json file within the CAS configuration. Below is the default state of this file on dbptke-enterprise (using CAS file):

{
  "admin": {
    "fullname": ["Administrator"],
    "email": ["[email protected]"],
    "memberOf": ["administrators", "users"]
  },
  "user": {
    "fullname": ["user"],
    "email": ["[email protected]"],
    "memberOf": ["users"]
  }
}

How Membership Works

• The user user has the memberOf attribute set to users.
• Since the Users authorization group defined above checks memberOf for the value users, this user is automatically included in the Users group.
• If permissions for the Users group are assigned to a database, all users in this group will have access to it but only after browsing.
• Group permissions can be managed through the Permissions panel of a database in the admin interface.

Note that attributeName is configurable. If you, for example, want the attributeName to be role instead of memberOf just change it its value on the property user.attribute.roles[]:

user.attribute.roles[]=role

You can have multiple attributes. If you did such change note that the attribute-repository.json would have to be updated to:

{
  "admin": {
    "fullname": ["Administrator"],
    "email": ["[email protected]"],
    "role": ["administrators", "users"]
  },
  "user": {
    "fullname": ["user"],
    "email": ["[email protected]"],
    "role": ["users"]
  }
}

Assigning Default Access to Groups

To grant all users in a specific authorization group default access to all databases, add the following configuration:

collections.authorizations.default.roles[]=<group_attributeValue>

For example, to allow the Users group defined above to access all inserted databases by default, use:

collections.authorizations.default.roles[]=users

Any user belonging to the specified group will automatically gain access to all databases ingested. However, note that users can only view databases after they have been indexed.

config/theme/*

The files in this folder are used to customize the user interface.

The theme.css and theme.js files are always loaded, and if the rules/behaviour they specify will be applied after the existing defaults (allowing these files to override the defaults).

The nobranding.css is a file that is loaded when the parameter branding=false is present in the URL.

Remove branding (header and footer)

This option can be used to embed the viewer in another page (for instance, via iframe) by passing the URL parameter branding=false, e.g. http://dbviewer-address/?branding=false#database.

The "nobranding" rules can be customised by changing the nobranding.css file.