This guide provides steps to install and configure client and server MQTT mosquito

• openSSL 3.0.13 (full) or newer, it can be downloaded from https://wiki.openssl.org/index.php/Binaries, install or extract files.
• Visual Studio 2022
• Inno Setup 6.2

Certificates must be generated before publishing SanjelMessagingInstaller, ensuring they are ready upon the application's publish completion. Please generate them only once, this prevents the certificates from being overwritten, so both sets of certificates (client and server) match once deployed, when certificates expire, follow these steps to generate them again.

Under SanjelMessagingInstaller\Certificates folder, open ConnectionCertificates.ps1 and modify variables:

$subject = "/CN=Sanjel Messaging/C=CA/ST=Alberta/L=Calgary/O=Sanjel/OU=IT" => Certificate properties: CN = Certificate name; C=2 characters country; ST= 2 characters State or province; L=City; O = Organization; OU = Organization unit
$days = 365 => Days the certificate will be valid
$passphrase = "*******" => "Password of the certificate"
$dnsServersConfig = "sanjel08.snj.local,sanjel08"  =>  Domain that is used to connect to mosquitto server (Server domain). Comma separated values
$ipServersConfig = "10.10.100.7"  =>  IP that is used to connect to mosquitto server (server IP). Comma separated values
$openSSLPath = "C:\Program Files\OpenSS\bin" => Path of bin OpenSSL files

• Run the Script Enter .\ConnectionCertificates.ps1 to run your script in a powershell window

Generated certificates are in the Assets folder and distributed with the application, these certificates can be used for local/development (manually testing).

For the automated workflow process using GitHub Actions, save certificates and keys in the SanjelMessaging Repository Environment secrets. This ensures that the certificates are securely stored and accessible during the GitHub Actions Workflow.

For binary (pfx) certificates, use the "convert Bin to Base64.ps1" utility to convert them into base64 strings so you can save the pfx certificate in Github environment secrets. This script can be found in the Certificates folder.

IMPORTANT certificates must match server IP/Domain or they will be invalid. Make sure all certificates share the same authority Id

Generate certificates again following steps above, save certificates and keys in environment secrets, run the desired workflow (uat, develop, etc). once the setup files are generated:

• For users (client PC): Ensure no messages are being published to a local Mosquitto broker (Service Express or another app). Confirm that all messages were forwarded to the remote Mosquitto broker (this step should be automatic as long as the client PC has a connection to the remote broker). Execute the Mosquitto client setup to copy certificates again, or copy only the certificates and restart the Mosquitto service.

• For Mosquitto remote (server) broker: You can just copy new certificates and keys. Alternatively, back up the database, execute the server setup file again, and restore the database file.

• Open the solution.
• Under the SanjelMessagingInstaller project, edit the App.config within the appSettings section.
  These variables are utilized during the execution of the installer on either client or server
  • MosquittoInstallationFile => mosquitto installer file name (it is under Assets folder)
  • remoteMosquittoAddress => Remote address (server address) (domain should be preferred, TLS certificates MUST match)
  • localMosquittoPort => Listening port for client setup
  • remoteMosquittoPort => Listening port for mosquitto server
  • windowsServiceName => For multiple instances change the windows service name
  • localUser => Local user name for connections like eServiceExpress
  • remoteUser => moquitto user name for Server
  • bridgeName => Label identifier of the bridge in the config file (this value besides to identify the bridge, it is used for confirmation messages (confirmBridgeName + ComputerName + _ + bridgeName)
  • mosquittoPath => Absolute path for Mosquitto binary files, (default path where mosquitto is installed). Change it for multiple instances
  • mosquittoDBPath => Mosquitto DB (it should have enough space / backup capacity). only for Server installer
  • certificatesBasePath => Base folder path which contains certificates for encryption (ca.crt, server.crt, server.key, client.crt, etc)
  • publishBridgeName => This is the topic that client application and local mosquitto use to forward messages to the remote mosquitto server, server application listen to this topic to process messages
  • confirmBridgeName => This is the topic used by the server to send a confirmation message and the client to subscribe to confirm the message
  • remotePassword => mosquitto remote server password
  • localPassword => mosquitto local password

• Go to SanjelMessaging repository page.
• Click on the "Settings" (it requires admin permissions) tab near the top of the page.
• In the left sidebar, click on "Environments".
• Find the environment you want to edit secrets/variable for and click on its name.
• Scroll down to the "Environment secrets/variables" section.
• Find the secret in the list and edit it. The secret or variable name ends with the same name as in the above list.

Push your changes to a desired Branch, the GitHub workflow will use secrets according to the environment and generate installers and servers.

There are two versions of the installer: one for the server and one for the client. The publisher configuration packages the application in .NET 6 for Windows x64.

• Right click on the project and select publish
• Select one version (server, client)

• Click publish
• Repeat for the other version (server or client)

• IMPORTANT!. It requires that app installer was published (see previous step)
• Open either Client or Server version to generate a setup file under Messaging\MessagingInstallerSetup folder

• Click on Build -> Compile to generate a setup file

• A installation package is generated under output folder
• Repeat for the other version (server or client)

• Run the MessagingInstaller server.exe You may change the default installation directory and/or database directory, for instance, when managing multiple instances. If you remove or leave empty the path, it will default to the value in App.config (mosquittoPath, mosquittoDBPath).

• Run the MessagingInstaller Client.exe You may change the default installation directory. If you remove or leave empty the path, it will default to the value in App.config (mosquittoPath).

If any of the clients or server have connection problems a log can be accessed in "mosquittoPath" + Log.log for both client and server

To monitor mosquitto in real time:

• Stop mosquito service in windows services
• Open mosquitto.conf and comment out log_type (error and warning) and log_dest.
• Run in a command line console mosquitto -c mosquitto.conf -v

Client applications (eServiceExpress, eService, etc) do not use any certificates.

if some error messages are displayed when generating certificates, please first confirm the certificates are generated, some error messages are false positives

Note For security reasons, PowerShell does not allow scripts to run by default. If you receive an error about the execution policy, you may need to change it. You can use the Set-ExecutionPolicy command to change the execution policy. For example, you can enter Set-ExecutionPolicy RemoteSigned to allow downloaded scripts to run as long as they have been signed. You should only change the execution policy if you understand the consequences and trust the script you are running.For example, you can enter powershell Set-ExecutionPolicy -Scope CurrentUser Unrestricted

Set-ExecutionPolicy -Scope CurrentUser Unrestricted

1. Install Server Broker on eService Server

2. Deploy Server application which subscribe to the Server Broker. (make sure you configure ‘Application Initialization’ in IIS so the app starts automatically). ‘Application Initialization’ feature must be installed on the IIS server to enable the automatic execution of the Message server application using the web.config configuration, without the need for a web request.

   • 

   • Message as the client Mosquitto and the server Mosquitto connection tool need to set the site to always run. Here are two Iss configuration properties

     1. Set to enable preloading in the advanced properties of the application:

     

     

     2. Set the startup mode of the application connection pool to always run.

     

3. Install Local Broker on each user's computer which is running eServiceExpress or EService, etc.

4. Deploy client application which subscribe to Local Broker

  

graph LR
    A[Client App] <--> B[Local Mosquitto Broker]
    C[Remote Server Mosquitto Broker]
    D[Remote App Server]

    subgraph "PC Client"
        A
        B
    end

    subgraph "Remote Network/Server"
        C
        subgraph "IIS"
        D
        end
    end

    B <-.->|SSL| C
    C <-.->|"SSL (PFX)"| D

1. Does the SanjelMessagesCert need to be there always? yes, certificates are always used to encrypt the connection

2. The ‘Application Initialization’ feature must be installed on the IIS server to enable the automatic execution of the Message server application using the web.config configuration, without the need for a web request.

3. Deployment tips.

• Sanjel Server version: Windows Server 2022 Datacenter
• Framework installation: dotnet-hosting-6.0.35-win.exe
• Both ExpressMessagingServer and PlcMessagingServer can be deployed to IIS
  • Website's Preload Enabled is True
  • Application pool's Start Mode must be AlwaysRunning, Identity must be LocalSystem