Install Hermod (docker)

This article describes how to install the Smart ID Messaging component Hermod as a docker image. For information about how to install Hermod as a WAR file, see Install Hermod (WAR file).

From Hermod version 3.5.0, swagger is enabled by default. To view an example, see "Edit Hermod configuration" below.

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

Prerequisites for docker installation

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

Step-by-step instruction

Download the Hermod docker image and file structure

Sign in to Nexus Support portal.
Go to Nexus Smart ID Clients (Personal and Hermod) > Smart ID Messaging and select a Hermod version to download the *.zip file.
Unpack the *.zip file.
Open the extracted folder, for example, 3.x.y.RELEASE.
The folder contains the Hermod installation file and a simple-setup file to set up a default configuration.
Unpack simple-setup.zip.

Default file structure

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

CODE

example/

`-- compose

    `-- hermod

        |-- cacerts

        |   `-- clientcert.cer

        |-- certificates

        |   `-- hermod-host-bundle.p12

        |-- config

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

        |   `-- README.txt

        |-- docker-compose.yml

        |-- postgresql

        |   `-- data

        `-- testdb

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 file name cannot contain spaces.
Put one or multiple certificate containers, including the whole certificate chain with any intermediate CA certificates, in pkcs#12 format (with a .pfx or .p12 extension) in the folder example/compose/hermod/certificates. The file name cannot contain spaces.

You must include intermediate CA certificates.

The certificate containers are referred to from the configuration file application.yml. For more information, see "Edit Hermod configuration".

Load docker image

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

Load the released docker image locally on the target host:

Example: Load docker image

TEXT

> docker load -i hermod-3.x.y.RELEASE.tar

If you have a docker registry, load the image in the docker registry.

Edit docker compose configuration

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

Important! The actual values must match the specific deployment scenarios. The docker-compose.yml code below is only intended as an example.

Edit the configuration file docker-compose.yml with the correct values for your environment.

Example

Example: docker-compose.yml

CODE

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 the context path and URI base is /hermod/rest/ (that is http://localhost:20400/hermod/rest/...).

Example

You can change the context path and URI base 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:

Example: Hermod start command

TEXT

hermod:
  ...
  command: "--server.servlet.context-path=/ ......"

You must also set the URI base to empty in the Hermod configuration.

Edit Hermod configuration

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

For more information, see Add API user and callback URL in Hermod.

Edit the configuration file config/application.yml with the correct values for your environment.

The actual values must match the specific deployment scenarios such as configure clientId, public URL, TLS/SSL and url, username, password for the specified database. The code below is only intended as an example.

Example

Example

CODE

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
    com.nexusgroup.cod.hermod.service.MessagePlugoutService: ERROR
    org.hibernate.engine.jdbc.spi.SqlExceptionHelper: OFF
  pattern:
    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:
    env:
      enabled: true
 
server:
  ssl:
    # When you enable security below you must put a real certificate in the certificates directory
    # and also change all http to https in this file + docker-compose.yml
    enabled: false
    key-store: /home/docker/certificates/hermod-host-bundle.p12
    key-store-password: "PASSWORD"
    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    
    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

Change URIbase

To change the uribase, for example, set the corresponding variable to empty, in the application.yml configuration file:

Example: Set uribase to empty

TEXT

application:
  hermod:
    rest:
      uribase: ""

Initialize database

Start the specified database. See Docker compose configuration file. This example show how to start PostgreSQL.
Example: Start PostgreSQL
TEXT
```
> cd example/compose/hermod
> docker-compose up -d postgresql
```

The Hermod docker image does not have a database. The docker compose config file example will pull the PostgreSQL image from docker hub.

Connect to your database and run the SQL ddl for the specific vendor or version, for example, postgresql/V3.1.1__base_version.sql.

Start Hermod and Hermod test app

Start Hermod with the following command:

Example: Start Hermod

TEXT

> docker-compose up -d hermod
> docker-compose logs -f

To install and start the Hermod test application, see Install Hermod test app. The test application can be used for basic tests.

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. To verify this, open the Hermod public URL in a browser and make sure the connection is secure, by viewing the padlock in the browser bar.

Example: Hermod public URL

TEXT

https://messagingservice.go.nexusgroup.com/ms

Additional information

Useful links