Versions Compared

Old Version 20

changes.mady.by.user Ylva Andersson

Saved on

compared with

New Version Current

changes.mady.by.user Ylva Andersson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated link.

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 3.x (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

  1. Sign in to Nexus Support portal.

  2. Go to Nexus Smart ID Clients (Personal and Hermod) > Smart ID Messaging  and select a Hermod version to download the *.zip file. 

  3. Unpack the *.zip file.

  4. 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. 

  5. Unpack simple-setup.zip. 

Default file structure

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

Code Block
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

  1. 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.  

  2. 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.  

...

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
Code Block
languagetext
> 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

...

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
Code Block
languagetext
hermod:
  ...
  command: "--server.servlet.context-path=/ ......"

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

Edit Hermod configuration
Anchor
Edit_Hermod_configuration
Edit_Hermod_configuration

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

...

Expand
titleExample

Example

Code Block
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:

...

Code Block
languagetext
application:
  hermod:
    rest:
      uribase: ""

Initialize database

  1. Start the specified database. See Docker compose configuration file. This example show how to start PostgreSQL. 

    Example: Start PostgreSQL

    Code Block
    languagetext
    > cd example/compose/hermod
> docker-compose up -d postgresql

...

  1. 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:

...

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
Code Block
languagetext
https://messagingservice.go.nexusgroup.com/ms

Additional information

Expand
titleUseful links

...