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

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

1. Log in to Nexus Support portal.
2. Go to Nexus Personal > Nexus Personal Messaging server and click a Hermod version to download the *.zip file. 
3. Unpack the *.zip file.
4. 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. 
5. Unpack simple-setup.zip. 

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

   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

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. 

   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.  

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

1. If you want to load the released docker image locally on the target host:

   Example: load docker image

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

2. If you have a docker registry, load the image there.

To edit the docker compose configuration:

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

   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"
   

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

   Example: Hermod start command

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

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

To edit the Hermod configuration:

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

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

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

   Set uribase to empty

   application:
     hermod:
       rest:
         uribase: ""

1. Start the database, this example shows how to start Postgres:

   Example: Start Postgres

   > cd example/compose/hermod
   > docker-compose up -d postgresql

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

1. Start Hermod with the following command:

   Example: Start hermod and hermod-testapp

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

2. To install and start Hermod test app, which is a GUI that can be used for basic tests, see Install Hermod test app.

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

   Hermod public URL

   https://<my-hermod-public-url>

   Example: Hermod public URL

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