Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
  • Hermod
  • Install Hermod test app
  • Smart ID Messaging

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

    Note

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

    Expandall

    Prerequisites

    Expand
    titlePrerequisites
    • Knowledge about docker.

    • A host 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 or Maria DB.

    Step-by-step instruction

    Expand
    titleDownload 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 2.3.x.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
    titleDefault 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
    titleStore 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 filenames must not contain spaces. 
    2. 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 behaviour in the Smart ID Mobile App app, which is very difficult to troubleshoot.

      The certificate containers are referred to from the configuration file cod-hermod.yml. See below in the Hermod configuration section.  

    Expand
    titleLoad 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
    languagetext
    titleExample: load docker image
    > docker load -i hermod-2.x.y.RELEASE.tar
  • If you have a docker registry, load the image there.
  • Expand
    titleIf 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
    titleExample: 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:2.5.0.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.failFast=false --application.hermod.swagger.enabled=true"
    
  • 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
    languagetext
    titleExample: Hermod start command
    hermod:
      ...
      command: "--server.contextPath=/ ......"

    Also set the uribase to empty in the Hermod configuration, see the next step.

  • Expand
    titleIf needed, edit Hermod configuration

    To edit the Hermod configuration:

    Edit the configuration file config/cod-hermod.yml 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/cod-hermod.yml

    Code Block
    titleExample: cod-hermod.yml
    logging:
      level:
        org.springframework.context.annotation.AnnotationConfigApplicationContext: ERROR
        org.springframework.boot.SpringApplication: ERROR
        org.springframework.cloud.config.client: ERROR
        com.netflix: INFO
        com.nexusgroup: TRACE
        com.relayrides: INFO
      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}"
        
    server:
      ssl:
        enabled: true
        key-store: /home/docker/certificates/hermod-host-bundle.p12
        key-store-password: "PASSWORD"
        keyStoreType: PKCS12
    
    spring:
      datasource:
        url: jdbc:postgresql://mydbserver:5432/hermod
        # url: jdbc:mariadb://mydbserver:3306/hermod    
        # url: jdbc:sqlserver://mydbserver:1433;database=hermod
        username: postgres
        password: postgres@123 
    
      jpa:
        properties:
          hibernate:
             dialect: org.hibernate.dialect.PostgreSQLDialect
             # dialect: org.hibernate.dialect.MySQL5InnoDBDialect
             # dialect: org.hibernate.dialect.SQLServer2012Dialect 
        hibernate:
          ddl-auto: validate
    
    # If the server is exposed on internet without something limiting access to endpoints (not recommended), 
    # you should only enable specific endpoints and only allow management from localhost
    endpoints:
      enabled: false
      refresh:
        enabled: true      
      health:
        enabled: true     
      info:
        enabled: true       
      mappings:
        enabled: false
    
    
    management:
      address: 127.0.0.1
      security:
        enabled: false
    
    application:
      hermod:
        rest:
          log: false
          # Hide exception information from clients. 
          # This should be enabled in production since you shouldn't reveal too much information
          hideExceptions: false 
    
        events:
          # Hide sensitive log data. 
          # This should be enabled in production since you shouldn't reveal too much information
          hideSensitive: false
        
        # Command callback retries and the delay between each retry
        callback:
          attempts: 1
          retryDelay: 10
    
        # Hermod clients/users. Connecting clients must set X-Api-Key              
        allowedClients:
          # Note!
          # The X-Api-Key should be created using base64(clientId: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
          - clientId: default
            key: 0e12b3a181c447f1b7d1745858d8583e197743db5663447a9cd99b5d7548b18c
            # Optional username:password to be supplied for basic authentication in callbacks
            # callbackBasicAuth: username:password
            # The callback URL base for this specific client
            callbackUrl: http://localhost:20400/hermod/rest
          # X-Api-Key: aGVybW9kLXRlc3RhcHA6MjY5NzJkOGZhOTQxNGI4MWJmMzVjYzllNGI3YmY2NWU1MWZiYjEzNGFiMjY0MGFlYWJkM2U3N2U3ZjE0NDAwMg==
          - clientId: hermod-testapp
            key: 26972d8fa9414b81bf35cc9e4b7bf65e51fbb134ab2640aeabd3e77e7f144002
            # Optional username:password to be supplied for basic authentication in callbacks
            # callbackBasicAuth: username:password
            # The callback URL base for this specific client
            callbackUrl: https://<my-hermod-server>:20488/hermod-testapp/rest
    
    
        # Message server library settings
        messageServerLibrary:
        
          # Public URL to the 'south-bound' message API. Please note that this URL must be reachable
          # from your devices. Try to access it from the browser on your phone  
          # It can also be the URL to a proxy fronting Hermod (with SSL offloading etc) 
          publicUrl: https://<my-hermod-server>:20400/hermod/rest/ms
    
          # A string to use for the {@code X-Powered-By} header.
          poweredby: Nexus

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

    Code Block
    languagetext
    titleSet uribase to empty
    application:
      hermod:
        rest:
          uribase: ""
    Expand
    titleInitialize database

    Start Postgres (unless you have you own, external instance running):

    Code Block
    languagetext
    titleExample: 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/V2.3.x_base_version.sql.

  • Expand
    titleStart Hermod

    Start Hermod with the following command:

    Code Block
    languagetext
    titleExample: 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
    titleVerify 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
    languagetext
    titleHermod public URL
    https://<my-hermod-public-url>
    Code Block
    languagetext
    titleExample: Hermod public URL
    https://messagingservice.go.nexusgroup.com/ms

    Related information

    is now deployed as part of Smart ID. See Deploy Smart ID