Skip to main content

Hanami ext folder

The ext folder contains configuration files and resources that define the behavior of the Hanami application. It has the following structure:

  • boot/: Contains Trig files (.trig) to be loaded into the internal triple store. Those are loaded only the first time hanami is booted, unless backups are disabled (see hanami.backup.enabled in config/customer.yml) below.
  • collections/: Contains configuration for the various collections (see detailed section here).
  • config/: Contains configuration yaml files. There should at least be customer.yml and security.yml. Profile-specific files can also be included here.
  • environment-changes/: Contains SPARQL queries (.sparql) to be run on the data in the boot folder before loading. These are mainly used to correctly configure the external RDF store for different environments. The hanami.customer.template-arguments property in customer.yml defines values to be templated in these queries.
  • operations/: Contains operations.json5 that defines the possible operations that are checked before allowing CRUD operations. This implements a role-based access control system and is only used for admin access in environments using WAC. This should not be edited.
  • config.json5: Contains configurations mostly related to access control.

config/ folder​

The config/ folder contains at least a customer.yml file and a security.yml file.

customer.yml​

This file contains customer-specific configuration.

  • hanami.authorization.provider: Specifies the authorization provider, either operations or wac.
  • hanami.elasticsearch.url: URL for Elasticsearch, typically referenced from environment variables.
  • hanami.lang.app: Application language settings:
    • default-lang: Default language for the application UI (e.g., en).
    • available-langs: List of available languages for the application UI (e.g., ['en', 'fr']).
    • locale-mapping: Maps language codes to locale codes (e.g., fr → fr-BE).
  • hanami.lang.data: Data language settings:
    • available-langs: List of available languages for data (e.g., ['en', 'fr']). This is used to give default possible languages for the hanami:LangStringEditor widget if no sh:languageIn is given.
  • hanami.prefixes: Namespace prefixes used throughout the application for RDF data, defining shorthand references to URIs (legacy config, will be removed in the future).
  • hanami.sync: Settings that allow Hanami to send synchronization events to a paired catalogue application.
    • eventTransmission.enabled: When true, Hanami emits create/update/delete event payloads so the paired application can stay in sync.
    • catalogue.baseUrl: Base URL of the REST endpoint exposed by the paired catalogue application.
    • catalogue.username: Username used for HTTP Basic authentication when invoking the catalogue endpoint.
    • catalogue.password: Password for HTTP Basic authentication. Prefix {noop} keeps it in plain text (suitable only for development); in production you should encode the password (e.g., {bcrypt}…) or store it in a secrets manager.
  • local.assets.folder: path to set a deep override of the UI asset folder. More on this here.

Example of a customer.yml file:

hanami:
  authorization:
    provider: operations # alternative: wac
  elasticsearch:
    url: ${env.hanami.elasticsearch.url}

  lang:
    app:
      default-lang: en
      available-langs:
        - en
        - fr
      locale-mapping:
        en: en-UK
        fr: fr-BE
    data:
      available-langs:
        - en
        - fr

  prefixes:
    dct: http://purl.org/dc/terms/
    hanami: https://hanami.app/ontology#
    owl: http://www.w3.org/2002/07/owl#
    prov: http://www.w3.org/ns/prov#
    rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
    rdfs: http://www.w3.org/2000/01/rdf-schema#
    schema: http://schema.org/
    sh: http://www.w3.org/ns/shacl#
    skos: http://www.w3.org/2004/02/skos/core#
    vcard: http://www.w3.org/2006/vcard/ns#
    xsd: http://www.w3.org/2001/XMLSchema#

  sync:
    eventTransmission:
      enabled: true
    catalogue:
      baseUrl: "http://paasbld006.ep.parl.union.eu:80"
      username: "hanami-app"
      password: "{noop}hanami-secret-pass"

local:
  assets:
    folder: /opt/hanami/ext

security.yml​

This file contains the security-related configuration and can have the given properties:

  • cognizone.security.auth-method: Authentication method, basic or saml. # TODO I suppose that oauth will come here?
  • cognizone.security.basic-auth: Basic authentication configuration:
    • realm: Authentication realm message.
      • users: User definitions with:
        • password: Encrypted password (typically BCrypt format).
        • roles: List of roles assigned to the user (e.g., 'ADMIN', 'EDITOR').

Example of a security.yml file:

cognizone:
  security:
    auth-method: basic
    basic-auth:
      realm: Hanami is asking who you are
      users:
        admin:
          password: "{bcrypt}$2a$12$QwLcj3Tu/sSTNF9RfctXBe2AGFO4GBBjOLXWVVvs1OnZPQAUbuo82" # admin/admin
          roles:
            - ADMIN
        editor:
          password: "{bcrypt}$2a$12$eUJ1BsUCkXK9Jr8i5KLu5.HHmhB/dzWr2ZtXz7.0EZJe.qRDCXROS" # editor/editor
          roles:
            - EDITOR

Profile-specific files​

Profile-specific YAML files can also be included in the config/ folder, which may override settings in the base configuration files for different deployment environments. These files follow the naming convention application-{profile}.yml and are loaded based on the active Spring profile.

Profile-specific files can:

  1. Override settings from base configuration files
  2. Provide environment-specific configurations
  3. Split configuration into logical sections for better maintainability

Common configurations in profile-specific files include:

  • env: Environment-specific variables and settings, used to be references in other files to make references to. Can contain anything.

  • hanami.index: Indexing configuration

    • full-node-indexing.enabled: Whether full node indexing is enabled or not (should be true for newer installations)
    • startup.workspaces: Whether to index workspaces at startup
    • startup.collections: Whether to index collections at startup

  • hanami.features: Feature toggles for the environment

    • validation.enabled: Whether validation features are enabled
    • actions.enabled: Whether action features are enabled

  • hanami.backup: Backup configuration

    • enabled: Whether backups are enabled
    • backup-rate-ms: Backup frequency in milliseconds
    • backup-delay-ms: Delay before first backup in milliseconds
    • clean-rate-ms: Cleanup frequency in milliseconds
    • clean-delay-ms: Delay before first cleanup in milliseconds

  • hanami.customer.template-arguments: Environment-specific template arguments. Typically a map of strings for variable to be used in templated sparql queries.

  • info.app.environmentName: Human-readable name for the environment, displayed in the top-right part of the UI.

Example of a profile-specific file structure:

env: # can contain anything
  cognizone:
    security:
      auth-method: basic
  hanami:
    id: hanami-dev
    elasticsearch:
      url: http://elasticsearch-dev:9200/

hanami:
  index:
    full-node-indexing:
      enabled: true
    startup:
      workspaces: true
      collections: true
  features:
    validation:
      enabled: true
    actions:
      enabled: true
  customer:
    template-arguments:
      rdfStore: http://rdf-store-dev:8890/sparql
      rdfStoreUser: dba
      rdfStorePassword: password123
      serviceAHost: http://localhost:8080
      serviceAAuthHeaders: Basic YWRtaW46YWRtaW4=

info:
  app:
    environmentName: Development Environment

For better maintainability, profile-specific configurations can be split across multiple files (e.g., application-profile1.yml, application-profile2.yml, application-profile3.yml), which will be combined when the corresponding profiles are active.

config.json5​

This file contains configurations that should eventually move to RDF in the admin workspace. It primarily defines security-related settings and access control for different parts of the application. In details:

  • security.collections: Maps CRUD keywords in the application to their corresponding operations to be checked for authorization.
  • security.endpoints: Defines role-based access control for specific API endpoints.
  • security.workspaces: Defines which workspaces are accessible to users with specific roles.
  • security.isDefaultAllowed: A boolean flag that determines whether users can access collections that are not explicitly configured in the access control settings.

Example of a config.json5 file:

{
  security: {
    collections: {
      create: "crud-download/create-check",
      read: "crud-download/read-check",
      update: "crud-download/update-check",
      delete: "crud-download/delete-check",
      download: "crud-download/download-check",
    },
    endpoints: {
      "api/admin/index": {
        "index-workspaces": ["ADMIN"],
        "index-collections": ["ADMIN"],
        "index-items": ["ADMIN"],
        "index-delete": ["ADMIN"],
        "index-query": ["ADMIN"],
      },
      "api/admin/index/is-running": {
        "is-running": ["ADMIN"],
      },
      "api/admin/tools/yasgui/sparql-endpoints": {
        "get-endpoints": ["ADMIN", "EDITOR"],
      },
      "api/admin/tools/yasgui/run": {
        "query-endpoint": ["ADMIN"],
      },
      "api/admin/backup": {
        create: ["ADMIN"],
      },
    },
    workspaces: {
      ADMIN: [
        "https://data.hanami.app/config/workspace/1",
        "https://data.hanami.app/config/workspace/data",
        "https://data.hanami.app/config/workspace/external-data",
      ],
      EDITOR: ["https://data.hanami.app/config/workspace/data"],
    },
    isDefaultAllowed: true,
  },
}