# Configuring GraphDB¶

GraphDB 9.x relies on several main directories for configuration, logging, and data.

What’s in this document?

## Directories¶

### GraphDB Home¶

The GraphDB home defines the root directory where GraphDB stores all of its data. The home can be set through the system or config file property graphdb.home.

The default value for the GraphDB home directory depends on how you run GraphDB:

• Running as a standalone server: the default is the same as the distribution directory.

• All other types of installations: OS-dependent directory.

• On Mac: ~/Library/Application Support/GraphDB.

• On Windows: Users<username>AppDataRoamingGraphDB.

• On Linux and other Unixes: ~/.graphdb.

Note

In the unlikely case of running GraphDB on an ancient Windows XP, the default directory is Documents and Settings<username>Application DataGraphDB.

GraphDB does not store any files directly in the home directory, but uses the following subdirectories for data or configuration:

#### Data directory¶

The GraphDB data directory defines where GraphDB stores repository data. The data directory can be set through the system or config property graphdb.home.data. The default value is the data subdirectory relative to the GraphDB home directory.

#### Config directory¶

The GraphDB config directory defines where GraphDB looks for user-definable configuration. The config directory can be set through the system property graphdb.home.conf.

Note

It is not possible to set the config directory through a config property as the value needs to be set before the config properties are loaded.

The default value is the conf subdirectory relative to the GraphDB home directory.

#### Work directory¶

The GraphDB work directory defines where GraphDB stores non-user-definable configuration. The work directory can be set through the system or config property graphdb.home.work. The default value is the work subdirectory relative to the GraphDB home directory.

#### Logs directory¶

The GraphDB logs directory defines where GraphDB stores log files. The logs directory can be set through the system or config property graphdb.home.logs. The default value is the logs subdirectory relative to the GraphDB home directory.

Note

When running GraphDB as deployed .war files, the logs directory will be a subdirectory graphdb within the Tomcat’s logs directory.

### Checking the configured directories¶

When GraphDB starts, it logs the actual value for each of the above directories, e.g.,

GraphDB Home directory: /opt/test/graphdb-se-8.x.x
GraphDB Config directory: /opt/test/graphdb-se-8.x.x/conf
GraphDB Data directory: /opt/test/graphdb-se-8.x.x/data
GraphDB Work directory: /opt/test/graphdb-se-8.x.x/work
GraphDB Logs directory: /opt/test/graphdb-se-8.x.x/logs


## Configuration¶

There is a single config file for GraphDB. GraphDB loads the config file graphdb.properties from the GraphDB config directory.

A sample file is provided in the distribution under conf/graphdb.properties.

### Config properties¶

Config properties are defined in the config file in the following format:

propertyName = propertyValue, i.e., using the standard Java properties file syntax.

Each config property can be overridden through a Java system property with the same name, provided in the environment variable GDB_JAVA_OPTS, or in the command line.

Note

The legacy properties (e.g., owlim-license) in the config file are ignored, but they work if specified as system properties.

#### List of configuration properties¶

##### General properties¶

The general properties define some basic configuration values that are shared with all GraphDB components and types of installation:

Property name

Description

graphdb.home

Defines the GraphDB home directory

graphdb.home.data

Defines the GraphDB data directory

graphdb.home.conf

(only as a system property) Defines the GraphDB conf directory

graphdb.home.work

Defines the GraphDB work directory

graphdb.home.logs

Defines the GraphDB logs directory

graphdb.external-url

Provides an external URL used as an access point to GraphDB

graphdb.workbench.home

The place where the source for GraphDB Workbench is located

graphdb.external-url

Provides an external URL for accessing the Workbench

graphdb.license.file

Sets a custom path to the license file to use

graphdb.page.cache.size

The amount of memory to be taken by the page cache

Tip

The graphdb.external-url property is useful when creating a cluster with proxy or Docker.

Note

graphdb.workbench.external-url is considered a legacy property, and should not be confused with graphdb.external-url.

##### Network properties¶

The network properties control how the standalone application listens on a network. These properties correspond to the attributes of the embedded Tomcat Connector. For more information, see Tomcat’s documentation.

Each property is composed of the prefix graphdb.connector. + the relevant Tomcat Connector attribute. The most important property is graphdb.connector.port, which defines the port to be used. The default is 7200.

In addition, the sample config file provides an example for setting up SSL.

Note

The graphdb.connector.<xxx> properties are only relevant when running GraphDB as a standalone application.

##### Engine properties¶

You can configure the GraphDB Engine through a set of properties composed of the prefix graphdb.engine. + the relevant engine property. These properties correspond to the properties that can be set when creating a repository through the Workbench or through a .ttl file.

Note

The properties defined in the config override the properties for each repository, regardless of whether you created the repository before or after setting the global value of an engine property. As such, the global override should be used only in specific cases. For normal everyday needs, set the corresponding properties when you create a repository.

Property name

Description

Default value

graphdb.engine.entity-pool-implementation

Defines the Entity Pool implementation for the whole installation. Possible values are transactional or classic.

The default value is transactional. The transactional-simple implementation is not supported anymore.

graphdb.persistent.parallel.inferencers

Since GraphDB 8.6.1, inferencers for our Parallel loader are shut down at the end of each transaction to minimize GraphDB’s memory footprint. For cases where a lot of small insertions are done in a quick succession that can be a problem, as inferencer initialization times can be fairly slow. This setting reverts to the old behavior where inferencers are only shut down when the repository is released.

false

graphdb.engine.entity.validate

A global setting that ensures IRI validation in the entity pool. It is performed only when an IRI is seen for the first time (i.e., when being created in the entity pool). For consistency reasons, not only IRIs coming from RDF serializations, but also all new IRIs (via API or SPARQL), will be validated in the same way. This property can be turned off by setting its value to false.

true

Note

Note that IRI validation makes the import of broken data more problematic - in such a case, you would have to change a config property and restart your GraphDB instance instead of changing the setting per import.

### Configuring logging¶

GraphDB uses logback to configure logging. The default configuration is provided as logback.xml in the GraphDB config directory.

## Best practices¶

Even though GraphDB provides the means to specify separate custom directories for data, configuration and so on, it is recommended to specify the home directory only. This ensures that every piece of data, configuration, or logging, is within the specified location.

### Step by step guide¶

1. Choose a directory for GraphDB home, e.g., /opt/graphdb-instance.

2. Create the directory /opt/graphdb-instance.

3. (Optional) Copy the subdirectory conf from the distribution into /opt/graphdb-instance.

4. Start GraphDB with graphdb -Dgraphdb.home=/opt/graphdb-instance or set the -D option in Tomcat.

GraphDB creates the missing subdirectories data, conf (if you skipped that step), logs, and work.