Skip to content

Configuration

Jump to bottom
Ludovic Muller edited this page Jul 30, 2024 · 13 revisions

Extend from other configs

It's possible to inherit from other configuration files with the extends property. Multiple files can be given. The value is always an array. All files are merged in sequence starting at index 0 of the extends array. The current config is the last one merged to the complete config.

YAML JSON 
extends:
  - ./config-sparql.yaml
  - ./config-sparql-addons.yaml
 
{
  "extends": [
    "./config-sparql.json",
    "./config-sparql-addons.json"
  ]
}

Make sure to use files that exists. You can use either YAML or JSON files.

Server

All server-related settings can be found under the server property. The listener section contains all information about the listener. Server options are defined in the options section.

YAML JSON 
server:
  listener:
    port: 8080
    host: 0.0.0.0
  logLevel: info
  logFormat: pretty
  options:
    trustProxy: true
 
{
  "server": {
    "listener": {
      "port": 8080,
      "host": "0.0.0.0"
    },
    "logLevel": "info",
    "logFormat": "pretty",
    "options": {
      "trustProxy": true
    }
  }
}

The server.logFormat can take one of the following value: json or pretty.

If it is set to pretty, it will use pino-pretty as transport, else it will use the default JSON option from Pino.

By default, server.logFormat is set to pretty, which is great for development purposes.

For production, it is recommended to switch it to json as it would be easier to parse them using some tools.

Since Trifid is using Fastify under the hood, here is the list of available options: https://fastify.dev/docs/latest/Reference/Server/

Plugins

All plugins are defined in the plugins property. The value of the property is an object. Each plugin instance uses it own key. The order of loading the plugins is defined by the value of the order property, which is optional. The module property points to the module to load. A string is used that will be processed by ESM import().

Some additional properties:

  • paths: can either be a string or an array of strings: the paths where to load this particular plugin
  • methods: can either be a string or an array of strings: the HTTP methods to use for this specific plugin (by default, the plugin will be called on each call)
  • hosts: can either be a string or an array of strings: the hosts where to load this particular plugin

Some plugins provide default values for paths and methods if none are given.

YAML JSON 
plugins:
  static-assets:
    module: trifid-core/plugins/static.js
    order: 0
    paths: /static-assets
    config:
      directory: file:static
 
{
  "plugins": {
    "static-assets": {
      "module": "trifid-core/plugins/static.js"
      "order": 10,
      "paths": "/static-assets",
      "config": {
        "directory": "file:static"
      }
    }
  }
}

Configure plugins

Properties defined in globals are merged into the scoped config.

The value given in globals can be overwritten in the scoped config.

Using a null-value will prevent merging the specific property.

YAML JSON 
globals:
  endpointUrl: env:SPARQL_ENDPOINT_URL
plugins:
  sparql-proxy:
    module: "@zazuko/trifid-plugin-sparql-proxy"
    paths: /query
    config:
      endpointUrl: env:ENDPOINT_URL
 
{
  "globals": {
    "endpointUrl": "env:SPARQL_ENDPOINT_URL"
  },
  "plugins": {
    "sparql-proxy": {
      "module": "@zazuko/trifid-plugin-sparql-proxy",
      "paths": "/query",
      "config": {
        "endpointUrl": "env:ENDPOINT_URL"
      }
    }
  }
}

Plugin Factory

The plugin factory is called with a single argument trifid which will be an object. This object will have a property called config to access a configuration key (it will take globals and add every property from the config part defined in the plugin). To access a particular config field from the plugin (called particularField for example), the following can be used: trifid.config.particularField.

The trifid object also exposes the following fields:

  • logger: a logger to use (default supported log levels: 'fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent') ; the default log level can be configured using the server.logLevel key
  • server: the Fastify instance
const factory = async (trifid) => {
  const { config, logger } = trifid;

  // access a configuration property:
  const { particularField } = config;

  // …do things

  return {
    // Register default paths and methods, in case none was provided in the configuration file
    defaultConfiguration: async () => {
      return {
        paths: ["/plugin/path"],
        methods: ["GET"],
      };
    },
    routeHandler: async () => {
      // …do some things

      const handler = async (_request, reply) => {
        logger.debug("reached my custom plugin");
        // …do some things
        return reply.type("text/plain").send("Hello, world!\n");
      };
      return handler;
    },
  };
};

Template engine

The trifid-core package includes a simple template engine that plugins can rely on. The objective is to provide an simple, configurable and standard option to serve HTML content.

Here is all configuration fields:

template:
  files:
    main: path/to/another/default/layout.hbs
    header: path/to/another/header.hbs
    footer: path/to/another/footer.hbs
  partials:
    partialName1: path/to/a/partial.hbs
    partialName2: path/to/another/partial.hbs
  title: "Default Trifid instance title"
  scripts:
    - path/to/additional/script1.js
    - path/to/additional/script2.js
  styles:
    - path/to/additional/style1.css
    - path/to/additional/style2.css
  disableHeader: false
  disableFooter: false

The trifid-core package will try to do the following:

  1. read all entries in the files property
  2. load each file content, and map it with the key
  3. use the main entry as the default layout, and replace {{{ key }}} with the content of the file specified with that key.
  4. do some Handlebars transformations if some are specified in the layout

The default value of the <title> tag can be set by using the title value.

Some additional scripts and styles can be added by using the specified fields in the configuration.

If a plugin do not want to render the header or the footer part, they can rely on the disableHeader and disableFooter options.

For complex templates, usage of Handlebars partials can be required. Declare partials the same way you declare template files, but in the partials section instead of files. The partial can be accessible from templates by using {{> partialName}}, where partialName is the key of the partial you used in the configuration file.

Well-known configuration fields

To have things consistent across the majority of plugins, here is a list of configuration properties to use:

  • datasetBaseUrl: the base URL for this dataset
  • endpoint.default.url: the default SPARQL endpoint URL

GitHub repository - Issues - Open an issue - Documentation

Clone this wiki locally