How to configure a Gaffer instance

There are various configuration files for Gaffer, this page gives an overview of the commonly used files and how to tweak them for your project needs.

Here is an example file structure which suits a stand-alone deployment using docker:

Example Gaffer project structure

Click the plus symbols for a brief description of each file

├── config
│   ├── gaffer
│       ├── application.properties #(1)!
│       ├── data                   #(2)!
│       │   ├── neo4jExport.csv
│       ├── graph
│       │   └── graphConfig.json #(3)!
│       ├── schema
│       │   ├── elements.json #(4)!
│       │   └── types.json    #(5)!
│       └── store
│           ├── operationsDeclarations.json #(6)!
│           └── store.properties            #(7)!
│
└── docker-compose.yaml #(8)!

Properties file that generally sets the file locations of other Gaffer configs e.g. schemas (note these are the absolute paths inside the container).
Any data files, e.g. CSV, to be made available to the Gaffer container.
The graph config file to set id, description and other values for the graph.
This file holds the schema outlining the elements in the graph, e.g. the entities and edges.
This file defines the different data types in the graph and how they are serialised to Java classes. An example of the schema files can be found here
Config file for additional Gaffer operations and set the class to handle them on the store.
The General store properties, sets up what store to use and any additional configuration.
This file controls which containers will be started up and the configuration of them to ensure correct ports and files are available.

Application Properties

The application.properties file is used for configuring the settings used by a Gaffer REST endpoint. In general it borrows a concept from Spring Boot to allow any properties related to Gaffer.

All REST Properties

The properties in bold are usually required for the REST endpoint to start.

Property	Default	Description
`gaffer.graph.config`	None	Path String specifying the `graphConfig.json` file to use
`gaffer.schemas`	None	Path String specifying the directory to load schemas from
`gaffer.storeProperties`	None	Path String specifying the `store.properties` file to use
`gaffer.rest-api.basePath`	`rest`	String used to set the base path for the REST endpoint
`gaffer.rest-api.version`	`2.0.0`	String with version to use in REST response headers
`gaffer.graph.factory.class`	`uk.gov.gchq.gaffer.rest.factory.DefaultGraphFactory`	Class Name String for setting the Graph Factory to use
`gaffer.user.factory.class`	`uk.gov.gchq.gaffer.rest.factory.UnknownUserFactory`	Class Name String for setting the User Factory to use
`gaffer.package.prefixes`	`uk.gov.gchq`	Comma separated list of package prefixes to search for Functions and Operations
`gaffer.properties`	None	String CSV of properties to expose via the properties endpoint
`gaffer.properties.app.title`	`Gaffer REST`	String used as the page title for Swagger REST
`gaffer.properties.app.description`	`The Gaffer REST service.`	String used as the description for Swagger REST
`gaffer.properties.app.banner.colour`	`red`	String containing an HTML colour to use for page banner
`gaffer.properties.app.banner.description`	None	String to use for a single line page banner, not shown by default
`gaffer.properties.app.doc.url`	`https://gchq.github.io/gaffer-doc/latest/`	URL String used as the documentation link
`gaffer.properties.app.logo.link`	`https://github.com/gchq/Gaffer`	URL String used as the link when clicking on logo in Swagger
`gaffer.properties.app.logo.src`	`images/logo.png`	Path String for logo image used in Swagger
`gaffer.properties.app.logo.favicon.small`	`images/logo.png`	Path String for small favicon used by web server
`gaffer.properties.app.logo.favicon.large`	`images/logo.png`	Path String for large favicon used by web server

The example below shows how we set the file location properties of where the other config files are.

application.properties

gaffer.schemas=/gaffer/schema
gaffer.storeProperties=/gaffer/store/store.properties
gaffer.graph.config=/gaffer/graph/graphConfig.json

Graph Config JSON

Within the graphConfig.json file you can set various properties that relate directly to the Graph object.

The file is in JSON format, a list of keys and their usage are outlined below:

Key	Value Type	Description
`graphId`	`String`	Sets the ID of the graph.
`description`	`String`	Sets the description of the graph.
`otelActive`	`Boolean`	Toggles if Open Telemetry data should be reported (`false` by default).
`view`	`JSON`	A default `View` that will be applied to `Operations`.
`library`	`JSON`	Any additional libraries you wish to load.
`hooks`	`List`	List of JSON objects containing any additional `GraphHooks` to load.

The example below shows an example of how we could configure each of these:

Example graphConfig.json

{
    "graphId": "ExampleGraph",
    "description": "An example graph",
    "otelActive": true,
    "view": {
        "globalElements": [
        {
            "postAggregationFilterFunctions": [
            {
                "predicate": {
                "class": "uk.gov.gchq.koryphe.impl.predicate.IsLessThan",
                "orEqualTo": false,
                "value": "10"
                },
                "selection": ["ExamplePropertyName"]
            }
            ]
        }
        ]
    },
    "hooks": [
        {
            "class": "uk.gov.gchq.gaffer.graph.hook.FunctionAuthoriser"
        }
    ],
    "library": {
    "class": "uk.gov.gchq.gaffer.store.library.FileGraphLibrary"
}
}

If using a standard Map Store backed Gaffer deployment you can easily update the values within your graphConfig.json later. The new key value pairs will be updated upon restarting the graph (assuming the file is loaded correctly).

However, if you are using the Accumulo store, updating the graphId is a little more complicated since the graphId corresponds to an Accumulo table. This means that if you change the ID then a new Accumulo table will be used and any existing data would be lost.

Open Telemetry Reporting

As previously mentioned, you can activate Open Telemetry reporting on the graph using the otelActive option. This will use an auto configured instance of Open Telemetry that will start exporting reports.

It is recommended to configure the exporting so that you send reports to a tool such as Jaeger to perform analysis later. To configure Open Telemetry you can utilise environment variables, a subset of commonly used variables are below:

Variable	Description
`OTEL_SERVICE_NAME`	Sets the service name of the instance e.g. `gaffer`.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Sets the endpoint to export traces to, if using Jaeger this could be:`http://jaeger:4317`
`OTEL_TRACES_EXPORTER`	Allows setting a different exporter than the default of `otel`.

Note

Please see the Open Telemetry documentation for more information.

Store Properties

Within the store.properties file we configure the Gaffer store which is used by the Graph. By default you must provide a store class and a store properties class as seen below. There are several different stores which can be configured and require additional properties which can be found in the Store Guide Section.

Below is an example of a store.properties file for a Graph using an Accumulo store.

store.properties

# Default properties
gaffer.store.class=uk.gov.gchq.gaffer.accumulostore.AccumuloStore
gaffer.store.properties.class=uk.gov.gchq.gaffer.accumulostore.AccumuloProperties

# Accumulo specific config
accumulo.instance=accumulo
accumulo.zookeepers=zookeeper
accumulo.user=root
accumulo.password=secret

Operations Declarations JSON

Within the operationsDeclarations.json you can enable additional operations in Gaffer. By default Gaffer already includes most operations (please refer to the Operations Guide pages), however you may want to enable other operations or even add your own custom ones.

The example below shows how to enable the ImportFromLocalFile operation which already exists in the code base but isn't included by default.

operationsDeclarations.json

{
    "operations": [
        {
            "operation": "uk.gov.gchq.gaffer.operation.impl.export.localfile.ImportFromLocalFile",
            "handler": {
                "class": "uk.gov.gchq.gaffer.store.operation.handler.export.localfile.ImportFromLocalFileHandler"
            }
        }
    ]
}