This article describes how to install the Smart ID Messaging component Hermod.

NoteThis article describes legacy installation of Hermod

This article describes how to install the Smart ID Messaging component Hermod.

Note

This article describes legacy installation of Hermod, This is deprecated.

If you need to install a test system, see Install Hermod test app.

Note
This instruction is only an example and does not describe a system for production, which typically requires orchestration tools or Docker hosting platforms.

Note
From Hermod version 3.5.0, swagger is enabled by default. See also heading “If needed, edit Hermod configuration” below for an example.

Prerequisites

Expand

title	Prerequisites

Knowledge about docker.
A Linux host (Windows is not officially supported) with docker and docker-compose installed and configured
A public DNS name which devices can reach.
Matching certificates for the public address.
Installed instance of an SQL server, such as PostgreSQL, Microsoft SQL Server, Maria DB or Oracle.

Step-by-step instruction

Expand

title	Download Hermod release from Nexus support portal

Download the Hermod docker image and file structure from Nexus support portal.

Log in to Nexus Support portal.
Go to Nexus Personal > Nexus Personal Messaging server and click a Hermod version to download the *.zip file.
Unpack the *.zip file.
Open the folder which was extracted, for example 3.x.y.RELEASE. Here you find the Hermod installation file and a simple-setup file to set up a default configuration.

Unpack simple-setup.zip.

The following file structure will be created for configuration and certificate files:

Panel

title	Default file structure

example/

`-- compose

`-- hermod

|-- cacerts

| `-- clientcert.cer

|-- certificates

| `-- hermod-host-bundle.p12

|-- config

| |-- application.yml -> ./cod-hermod.yml

| |-- cod-hermod.yml

| `-- README.txt

|-- docker-compose.yml

|-- postgresql

| `-- data

`-- testdb

Expand

title	Store certificate files in the Hermod structure

Put one or multiple CA certificates in base64 format with .cer file extension in the folder example/compose/hermod/cacerts. The filenames must not contain spaces.
Put one or multiple certificate containers - including the whole certificate chain with any intermediate CA certificates - in pkcs#12 format (with .pfx or .p12 extension) in the folder example/compose/hermod/certificates. The filenames must not contain spaces.
Note
Failing to include intermediate CA certificates might produce erratic behavior in the Smart ID Mobile App, which is very difficult to troubleshoot.
The certificate containers are referred to from the configuration file application.yml (cod-hermod.yml). See below in the Hermod configuration section.

Expand

title	Load docker image

The docker image can be loaded locally to each machine, or to the docker registry, and used remotely from several machines.

If you want to load the released docker image locally on the target host:
Code Block
language text
title Example: load docker image
> docker load -i hermod-3.x.y.RELEASE.tar
If you have a docker registry, load the image there.

Expand

title	If needed, edit docker compose configuration

To edit the docker compose configuration:

Edit the configuration file docker-compose.yml with the correct values for your environment. Below you can find examples, but the actual values must match the specific deployment scenarios.

File path: example/compose/hermod/docker-compose.yml

Code Block

title	Example: docker-compose.yml

version: '2'

services:

  postgresql:
    restart: unless-stopped
    image: postgres:9.4.12
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=dbuser
      - POSTGRES_PASSWORD=dbpassword
      - POSTGRES_DB=hermod
      - TZ=Europe/Stockholm
    mem_limit: 256m
    volumes:
      - ./postgresql/data:/var/lib/postgresql/data:Z

  hermod:
    restart: unless-stopped
    image: nexusgocontainerregistry.azurecr.io/nexus-personal/hermod:3.1.1.RELEASE
    ports:
      - "20400:20400"
    extra_hosts:
      - "<my-hermod-server>:94.140.49.248"
    environment:
      - TZ=Europe/Stockholm
      - JAVA_OPTS=-Xms128m -Xmx256m -XX:MaxMetaspaceSize=256m -XX:CompressedClassSpaceSize=64m -Xss256k -Xmn8m -XX:InitialCodeCacheSize=4m -XX:ReservedCodeCacheSize=64m -XX:MaxDirectMemorySize=64m
    mem_limit: 512m
    volumes:
      - ./config:/home/docker/config:z
      - ./certificates:/home/docker/certificates:z
      - ./cacerts:/cacerts:z
    logging:
      options:
        max-size: 10m
    command: "--spring.cloud.config.fail-fast=false --springdoc.swagger-ui.enabled=false --springdoc.api-docs.enabled=false"

The default value for context path and uri base is /hermod/rest/ (that is http://localhost:20400/hermod/rest/...). You might want to change this for your specific configuration.
For example, if you want to change the context path and uri base to empty values, change the start command for Hermod in docker-compose.yml:
Code Block
language text
title Example: Hermod start command
hermod: ... command: "--server.servlet.context-path=/ ......"
Also set the uribase to empty in the Hermod configuration, see the next step.

logging: level: org.springframework.context.annotation.AnnotationConfigApplicationContext

config/cod-hermod.yml might be a link) with the correct values for your environment. Below you can find examples, but the actual values must match the specific deployment scenarios.

Default file path: example/compose/hermod/config/application.yml

Expand

title	If needed, edit Hermod configuration

Note
See also Add API user and callback URL in Hermod.

To edit the Hermod configuration:

Edit the configuration file config/application.yml (config/cod-hermod.yml might be a link) with the correct values for your environment. Below you can find examples, but the actual values must match the specific deployment scenarios.
Default file path: example/compose/hermod/config/application.yml

Code Block

title	Example: cod-hermod.yml

Code Block

title	Example: cod-hermod.yml

logging:
  level:
    org.springframework.context.annotation.AnnotationConfigApplicationContext: ERROR
    org.springframework.boot.SpringApplication: ERROR
    org.springframework.cloud.config.client: ERROR
    com.nexusgroup: TRACE
    com.nexusgroup.plugout.message.server.filters.VersionHttpFilter: ERROR
    org.springframework.boot.SpringApplicationcom.nexusgroup.cod.hermod.service.MessagePlugoutService: ERROR
    org.springframeworkhibernate.engine.cloudjdbc.configspi.clientSqlExceptionHelper: ERROROFF
    com.nexusgrouppattern:
TRACE     com.nexusgroup.plugout.message.server.filters.VersionHttpFilter: ERROR
    com.nexusgroup.cod.hermod.service.MessagePlugoutService: ERROR
    org.hibernate.engine.jdbc.spi.SqlExceptionHelper: OFF
  patternconsole: "%d{yyyy-MM-dd}T%d{HH:mm:ss.SSS}Z ${LOG_LEVEL_PATTERN:- %5p} [%t] %-40.40logger{39} [%mdc] : %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}"

# Enable info endpoint
management:
  info:
    env:
    console: "%d{yyyy-MM-dd}T%d{HH:mm:ss.SSS}Z ${LOG_LEVEL_PATTERN:- %5p} [%t] %-40.40logger{39} [%mdc] : %m%n${LOG_EXCEPTION_CONVERSION_WORD:%wEx}"

# Enable info endpoint
management:
  info:  enabled: true
 
server:
  ssl:
    # When you enable security below you must put a real certificate in the certificates directory
    env:# and also change all http to enabled:https truein this file server:
+ docker-compose.yml
 ssl:   enabled: false
# When you enable security below you must put a real certificate in the certificates directory
 key-store: /home/docker/certificates/hermod-host-bundle.p12
    key-store-password: "PASSWORD"
    key-store-type: PKCS12


# andTo also change all http to https in this file + docker-compose.ymldisable/enable apidocs/swagger-ui 
springdoc:
  override-with-generic-response: false
  api-docs:
    enabled: false
  swagger-ui:
 key-store: /home/docker/certificates/hermod-host-bundle.p12  enabled: false

key-store-passwordspring:
"PASSWORD"  datasource:
    key-store-type: PKCS12


# To disable/enable apidocs/swagger-ui 
springdoc:
  override-with-generic-response: false
  api-docs:
    enabled: false
  swagger-ui:
    enabled: false

spring:
  datasource: ## sqlserver jdbc driver use ssl encryption by default, to disable change it to encrypt=false. For more info: https://learn.microsoft.com/en-us/sql/connect/jdbc/understanding-ssl-support?view=sql-server-ver16
    # url: jdbc:sqlserver://mydbserver:1433;database=hermod;encrypt=true
    url: jdbc:postgresql://mydbserver:5432/hermod
    # url: jdbc:mariadb://mydbserver:3306/hermod    
    # url: jdbc:sqlserver://mydbserver:1433;database=hermod
    username: postgres
    password: postgres@123
    ### Oracle Database example
    # For SID, use the following url
    #url: jdbc:oracle:thin:@HOST_NAME:1521:SID_NAME
    #username: USER_NAME
    #password: PASSWORD
    # For Servername, use the following url
    # url:jdbc:oracle:thin:USER_NAME/PASSWORD@HOST_NAME:1521/SERVICE_NAME
 
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
        # dialect: org.hibernate.dialect.MySQL5InnoDBDialect
        # dialect: org.hibernate.dialect.SQLServer2012Dialect
        # dialect: org.hibernate.dialect.Oracle12cDialect
    hibernate:
      ddl-auto: validate
 
application:
  hermod:
    rest:
      log: false
      # Hide exception information to clients
      hide-exceptions: true
 
    events:
      # Hide sensitive log data. 
      # This should be enabled in production since you shouldn't reveal too much information
      hide-sensitive: true
 
    # Command callback retries
    callback:
      attempts: 3
      retry-delay: 10
 
    # Hermod clients/users. Connecting clients must set X-Api-Key              
    allowed-clients:
      # Note!
      # The X-Api-Key should be created using base64(client-id:key)
      #
      # Hermod has a helper endpoint to generate configuration. Simply use (make sure you have the correct host/port)
      # curl 'http://localhost:20400/hermod/rest/util/generateclient/default'
      # to get a snippet which can be pasted to the configuration file
      #
      # X-Api-Key: ZGVmYXVsdDowZTEyYjNhMTgxYzQ0N2YxYjdkMTc0NTg1OGQ4NTgzZTE5Nzc0M2RiNTY2MzQ0N2E5Y2Q5OWI1ZDc1NDhiMThj
      - client-id: default
        key: 0e12b3a181c447f1b7d1745858d8583e197743db5663447a9cd99b5d7548b18c
        # Optional username:password to be supplied for basic authentication in callbacks
        # callback-basic-auth: username:password
        # The callback URL base for this specific client
        callback-url: http://localhost:20400/hermod/rest
      # X-Api-Key: aGVybW9kLXRlc3RhcHA6MjY5NzJkOGZhOTQxNGI4MWJmMzVjYzllNGI3YmY2NWU1MWZiYjEzNGFiMjY0MGFlYWJkM2U3N2U3ZjE0NDAwMg==
      - client-id: hermod-testapp
        key: 26972d8fa9414b81bf35cc9e4b7bf65e51fbb134ab2640aeabd3e77e7f144002
        # Optional username:password to be supplied for basic authentication in callbacks
        # callback-basic-auth: username:password
        # The callback URL base for this specific client
        callback-url: https://<my-hermod-server>:20488/hermod-testapp/rest
  
    # Message server library settings
    message-server-library:
     
      # Make sure you also change the certificates above if ssl is used
      public-url: https://<my-hermod-server>:20400/hermod/rest/ms

If you want to change the uribase, set the corresponding variable, for example to empty, in the application.yml (cod-hermod.yml) configuration file:

Code Block

language	text
title	Set uribase to empty

application:
  hermod:
    rest:
      uribase: ""

Expand

title	Initialize database

Start the database, this example shows how to start Postgres:
Code Block
language text
title Example: Start Postgres
> cd example/compose/hermod > docker-compose up -d postgresql
Connect to your database and run the SQL ddl for the specific vendor/version, for example, postgresql/V3.1.1__base_version.sql.

Expand

title	Start Hermod

Start Hermod with the following command:
Code Block
language text
title Example: Start hermod and hermod-testapp
> docker-compose up -d hermod > docker-compose logs -f
To install and start Hermod test app, which is a GUI that can be used for basic tests, see Install Hermod test app.

Expand

title	Verify SSL certificate of Hermod public URL

Make sure that the public URL that has been configured in Hermod has a valid and trusted SSL certificate. This can be verified by opening the Hermod public URL in a browser and make sure the connection is secure, by viewing the padlock in the browser bar.
Code Block
language text
title Hermod public URL
https://<my-hermod-public-url>
Code Block
language text
title Example: Hermod public URL
https://messagingservice.go.nexusgroup.com/ms

This article is valid for legacy Hermod versions only.

Versions Compared

Old Version 13

New Version 14

Key

Prerequisites

Step-by-step instruction

Related information

Page Comparison

Versions Compared

Old Version 13

New Version 14

Key

Prerequisites

Step-by-step instruction

Related information