Intermediate Layer Installation Options

What are the different options available for operating an Intermediate Layer?

Where can I find the publicly available Intermediate Layer hosted by COSMO CONSULT?

How do I install an Intermediate Layer in a SaaS environment?

How do I install an Intermediate Layer in an on-premises environment?

Tip

Summary: This guide explains how to install the Intermediate Layer in both SaaS (cloud) and on-premises environments. For SaaS deployment, the Intermediate Layer can be hosted by COSMO CONSULT or in a private cloud environment. It uses Microsoft Azure services like CosmosDB, Azure Key Vault, and a Docker container running inside a Web App. The process involves setting up these services and configuring environment variables. For on-premises deployment, the Intermediate Layer is installed as a Windows Service.

Typically an installation is only performed once and is not executed by the user, but an administrator. The installation differs between SaaS (cloud) and on-premises environments.

SaaS Deployment

There are two scenarios for a SaaS deployment:

the COSMO CONSULT hosted scenario is used in cases where a company entrusts COSMO CONSULT with the operation of the Intermediate Layer and COSMO CONSULT performs the installation.
the Self-Cloud hosted scenario is used in cases where a company wants to host the Intermediate Layer in the cloud itself and take responsibility for its operation.

In both scenarios, there are additional costs associated with the chosen hosting option.

On-premises

Install the intermediate layer on a server as a Windows Service. This installation method is suitable for customers who prefer to host the intermediate layer privately within their infrastructure. There are no additional costs involved, apart from server maintenance and staffing.

Installation Processes

The details of the SaaS and On-Premises (OnPrem) installation processes are designated in the separate tabs below.

SaaS Installation
OnPrem Installation

For strictly demonstration and test purposes, COSMO CONSULT provides a publicly available intermediate layer.

This guide will go through the installation steps for the intermediate layer in an Azure environment. The intermediate layer is an app service-based application that runs a docker container inside. For the persistent data storage it uses CosmosDB. Additionally, it uses an Azure storage account for storing the logs if needed.

Requirements

Microsoft Azure subscription (or other cloud service subscription with container run capability. Microsoft Azure is highly recommended).
Ability to create resource groups, container instances, Azure KeyVault instances and Azure COSMOSDB instances.

Installation Steps

Create a new resource group in the Azure portal. This resource group will contain all the resources needed for the intermediate layer.
Create a new CosmosDB for NoSQL database.
Set the Workload Type to Production, select your Resource Group and then fill in the Account Name. Select a Location close to you and then set the Capacity mode as Serverless.
On the Global Distribution tab, set the Geo-Redundancy to Disable.
Set Connectivity method to All networks on the Networking tab.
On the Backup Policy tab, choose the relevant Backup storage redundancy. We use Locally-redundant backup storage as default.
On the Security tab make sure the Key-based Authentication is enabled.
Go to the Review + create tab and then choose the Create button.
While it's creating, create a new Azure Key Vault.
On the Basics tab, select your Resource group, fill in the Key vault name and select your Region.
On the Access configuration tab, select Vault access policy as the Permission model.
On the Networking tab, set Enable Public access to True.
Go to the Review + create tab and choose the Create button.
Go back to the newly created CosmosDB and choose Keys in the navigation pane. Copy the Primary Connection String.
Go to the newly created Key Vault, choose Secrets in the navigation pane, and then choose Generate/Import.
Fill in the Name and paste the copied Primary Connection String (from step 12) to the Secret value field. Choose the Create button.
Now, create a new Web App. On the Basics tab, select your Resource Group, fill in the App Name, select Container as Publish, select Linux as the Operating System, and then select your Region. Lastly, select a Linux app service plan if you have one, if not create a new B1 plan.
On the Container tab, disable Sidecar Support, select Other container registries as the Image Source and then fill in the Image and tag field. The image can be found on the Docker Hub. To know which one to use, check the latest public version on COSMO Docs or ask your COSMO consultant.
On the Networking tab, make sure the Enable public access is set to On.
Go to the Review + create tab and then choose the Create button.
Go to the newly created Web App, and then select Identity in the navigation pane. In the System assigned tab, turn on the Status. Choose Save and then copy the value in the Object (principle) ID field.
Go to the Key Vault that you created earlier, choose Access policies in the navigation pane, and then choose Create to add an access policy.
On the Permissions tab, choose the Select all checkbox under the Secret permissions group.
On the Principal tab, search for and then choose the Object ID you copied earlier.
Go to the Review + create tab and then choose the Create button.

Copy the following code block to a notepad or a text editor on your computer and replace the <created-secret-name> and <created-keyvault-url> with the actual values.
The Key Vault URL can be found on the Overview tab of the Key Vault.

Key Vault Overview

[
  {
    "name": "CCMS_AzureKeyVaultCosmosSecretKey",
    "value": "<created-secret-name>",
    "slotSetting": false
  },
  {
    "name": "CCMS_AzureKeyVaultEndpoint",
    "value": "<created-keyvault-url>",
    "slotSetting": false
  },
  {
    "name": "CCMS_CosmosDatabaseName",
    "value": "MobileSolution_Staging",
    "slotSetting": false
  },
  {
    "name": "CCMS_HttpPort",
    "value": "80",
    "slotSetting": false
  },
  {
    "name": "CCMS_IsHttpEnabled",
    "value": "true",
    "slotSetting": false
  },
  {
    "name": "CCMS_IsOnPremInstallation",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "CCMS_ServerInstanceCacheLifetime",
    "value": "10080",
    "slotSetting": false
  },
  {
    "name": "CCMS_UseHTTPSRedirection",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "CCMS_UseSwagger",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "WEBSITES_ENABLE_APP_SERVICE_STORAGE",
    "value": "false",
    "slotSetting": false
  },
  {
    "name": "DOCKER_REGISTRY_SERVER_URL",
    "value": "https://index.docker.io/v1",
    "slotSetting": false
  }
]

Go to the Web App that you created earlier and select Environment variables in the navigation pane. Choose Advanced edit and then paste the code block you modified in the previous step. Click the OK button and then the Apply button.
Go to the Overview tab of the Web App, choose Stop on the action bar, wait 1-2 minutes, and then choose Start on the action bar. This will restart the Web App with the new environment variables.
Copy the URL of the Web App (called Default Domain on the Overview page), paste it to your browser, and add /core/version suffix to it. This will show you the version of the intermediate layer you just created.
If you see the version, then you have successfully created the intermediate layer in the Azure environment.

Logging Options

Select at least one of the following options for logging:

Basic
Long Term

Basic Logging

This is the default logging option. The logs are stored in the app service itself. The logs are accessed from the Log stream tab of the Monitoring section in the Web App.

To set up basic logging

Go to the Web App and select App Service logs in the navigation pane.
Turn on the Application logging.
Enter 100 as Quota (MB) and set the Retention Period (Days) to 3.
Choose Save.

To later read the logs, choose Log Stream in the navigation pane (the stream updates every minute).

Alternatively, you can read the files via the Azure CLI tools. You can use the following command to download the logs: az webapp log download --name <name of the app service> --resource-group <name of the resource group>

The downloaded zip includes a LogFiles folder and the _default_docker.log suffixed file should contain the Intermediate layer logs.

Long Term Logging

It's possible to add a storage account to the Web App for storing the logs, which is useful if you want to keep the logs for a longer period of time.

To set up long term logging

Create a new Storage Account in the Azure portal.
On the Basics tab, select your Resource group, fill in the Storage account name, select your Region, and choose the relevant Redundancy. We use Locally-redundant storage (LRS) as default.
Go to the Review + create tab and then choose the Create button.
Go to the newly created Storage Account, select File shares in the navigation pane, and then choose File share.
Fill in the Name, go to the Backup tab, and then disable the backup.
Go to the Review + create tab and choose the Create button.
Go to the Web App that you created earlier and select Environment variables in the navigation pane. Choose Advanced edit on the action bar and then paste in the following code block, making sure to include the comma (,). Click the OK button and then the Apply button.
```
,
  {
    "name": "CCMS_Logging__Targets",
    "value": "File",
    "slotSetting": false
  }
```
In the navigation pane, choose Configuration and then choose the Path mappings tab. Choose New Azure Storage Mount.
Fill in the Name field, choose Advanced as the Configuration options, enter a name in the Storage accounts field, choose Azure Files as the Storage type, set the Protocol to SMB, enter the previously created Share name, and set the Mount Path to /app/_AppLogs_. Choose the OK button and then choose Save.
Open the previously created storage account on another tab, and then choose Access keys in the navigation pane. Below key1, choose the Show button at the end of the Key field, and then copy the value.

]
Fill in the Access key and then choose the OK button and then choose Save on the action bar.
Go to the Overview tab of the Web App, choose Stop on the action bar, wait 1-2 minutes, and then choose Start on the action bar. This will restart the Web App with and the Intermediate Layer will start with logging.

Description of Environment Variables

The following table describes the environment variables that are used in the intermediate layer and can be used to configure the IL behaviors. All should be prefixed with "CCMS_" and should be added to the Web App as environment variables.

Value Name	Function	Used for Azure Installation
IsOnPremInstallation	Intermediate layer will use the local database instead of Azure when it is set to "true".	✔️
IsHttpEnabled	Enables the HTTP protocol.	✔️
HttpPort	Sets the port for the HTTP traffic.	✔️
ServerInstanceCacheLifetime	Changes for how much time the server identifier will be cached, value must be set in minutes. -1 means it will cache for "infinite", the default is 7 days.	✔️
CosmosDatabaseName	Name of the database if it is in Azure. Recommendation: Keep as provided above.	✔️
AzureKeyVaultEndpoint	Endpoint URL of the key vault if the key vault is used to store the certificate file.	✔️
AzureKeyVaultCosmosSecretKey	Connection string for the CosmosDB.	✔️
UseHTTPSRedirection	If enabled, all HTTP traffic will be forwarded to HTTPS. For app services, set it to "false".	✔️
Logging__Targets (Optional)	By default, not part of the above mentioned values but can be added. The supported values are "File", "Debug" and "File,Debug". Enables the logger to write logs into File and/or Debug console.	✔️
UseSwagger	Used for development and/or debug only. Leave it set to "false".	✔️
AllowRemoteLogging	Enables remote logging to the development team, which can facilitate faster issue resolution.	✔️
RemoteLoggingTraceRate	Specifies the trace rate for remote logging. The value must be between "0" (no logging) and "1" (all logs are sent to remote storage). The recommended value is "0.2".	✔️
IsHttpsEnabled	Enables the HTTPS protocol. For app services, set it to "false".	❌
HttpsCertificateThumbprint	Thumbprint of the certificate, which is when HTTPS is enabled. It must be installed in the LocalMachine/My certificate store and the Service owner should have access to the certificates.	❌
HttpsPort	Sets the port for the HTTPS traffic.	❌
BusinessDataSQLiteFileName	Name of the database where the Server IDs will be saved.	❌
Obsolete ~~AzureKeyVaultHTTPSCertificateKey~~	~~Certificate file name in the key vault.~~	❌
Obsolete ~~AzureAppRegistrationTenantId~~	~~Tenant ID of the app registration, which is used for accessing the key vault.~~	❌
Obsolete ~~AzureAppRegistrationClientId~~	~~Client ID of the app registration, which is used for accessing the key vault.~~	❌
Obsolete ~~AzureAppRegistrationClientSecret~~	~~Client secret of the app registration, which is used for accessing the key vault.~~	❌

COSMO CONSULT provides an intermediate layer installation package as a NuGet package.

This section covers the installation of the intermediate layer as an OnPrem Windows Service.

Requirements

The requirements for installing the intermediate layer as a Windows Service are:

A server computer that runs Windows.
At least 1.5 GB RAM, and 1 server core.
CA signed SSL certificate for HTTPS.
Administration permission to install applications.
.NET 8 Runtime and ASP.NET 8 Runtime (Hosting Bundle is currently the easiest way to install them).

Installation Steps

Download the intermediate layer package as a NuGet package.
Create a dedicated directory for the intermediate layer in the desired location.
Extract the contents of the zip file into the newly created directory.
Open a command prompt with administrative privileges in the intermediate layer's directory.
Execute CosmoConsult.MobileSolution.Intermediate.WebAPIFacade.exe install to install the Windows Service (named COSMO Mobile Solution Intermediate Layer) with default settings.
Adjust the configuration as required. The following changes are recommended:
- Enable HTTPS by setting IsHttpsEnabled to "true" and specify the HttpsCertificateThumbprint for the certificate you intend to use.
- Disable HTTP by setting IsHttpEnabled to "false". If you are using a self-signed certificate, you may need to keep this enabled, as the Business Central HTTP Client does not support self-signed certificates.
- Configure the service to run under a dedicated user account rather than the default Network Service.
- Review firewall settings and ensure that the HttpsPort (and HttpPort, if necessary) are open to allow connectivity from the Business Central instance and handheld devices.
Start the service and verify its operation by checking the Intermediate Layer status page.

Configuration Settings

Configuration settings are separated into two categories: the intermediate layer's functional part and the IT-related part.

Intermediate Layer Configuration

Configuring the intermediate layer functional part is done in the file named "appsettings.Production.json". For a new installation, most of the settings are already set up but some need to be configured based on the environment. These settings are mostly the followings:

HttpPort
HttpsPort
IsHttpsEnabled
IsHttpEnabled
HttpsCertificateThumbprint.

The following image illustrates a sample configuration, showing how to assign HTTPS port 16001, HTTP port 16000, disable HTTP, enable HTTPS, and define the certificate thumbprint.

Basic Configuration

All settings are described in the following table.

Value Name	Function	Used for On-premise Installation
IsOnPremInstallation	Intermediate layer will use the local database instead of Azure when it is set to "true".	✔️
IsHttpsEnabled	Enables the HTTPS protocol.	✔️
HttpsPort	Sets the port for the HTTPS traffic.	✔️
UseHTTPSRedirection	If enabled, all HTTP traffic will be forwarded to HTTPS.	✔️
HttpsCertificateThumbprint	Thumbprint of the certificate, which is when HTTPS is enabled. It must be installed in the LocalMachine/My certificate store and the Service owner should have access to the certificates.	✔️
IsHttpEnabled	Enables the HTTP protocol.	✔️
HttpPort	Sets the port for the HTTP traffic.	✔️
BusinessDataSQLiteFileName	Name of the database where the Server IDs will be saved.	✔️
ServerInstanceCacheLifetime	Changes for how much time the server identifier will be cached, value must be set in minutes. -1 means it will cache for "infinite", the default is 1 day.	✔️
AllowRemoteLogging	Enables remote logging to the development team, which can facilitate faster issue resolution.	✔️
RemoteLoggingTraceRate	Specifies the trace rate for remote logging. The value must be between "0" (no logging) and "1" (all logs are sent to remote storage). The recommended value is "0.2".	✔️
CosmosDatabaseName	Name of the database if it is in Azure.	❌
AzureKeyVaultEndpoint	Endpoint URL of the key vault if the key vault is used to store the certificate file.	❌
AzureKeyVaultHTTPSCertificateKey	Certificate file name in the key vault.	❌
AzureKeyVaultCosmosSecretKey	Connection string for the CosmosDB.	❌
AzureAppRegistrationTenantId	Tenant ID of the app registration, which is used for accessing the key vault.	❌
AzureAppRegistrationClientId	Client ID of the app registration, which is used for accessing the key vault.	❌
AzureAppRegistrationClientSecret	Client secret of the app registration, which is used for accessing the key vault.	❌
UseSwagger	Used for development and/or debug only. Leave it set to "false".	❌
Logging/Targets (Optional)	By default, not part of the file but can be added inside the Logging. The supported values are "File", "Debug" and "File,Debug". Enables the logger to write logs into File and/or Debug console.	✔️
Obsolete ~~HttpsCertificateFilePath~~	~~Points to the location of the certificate file, which is used when HTTPS is enabled. Currently, only the ".pfx" format is supported.~~	❌
Obsolete ~~HttpsCertificatePassword~~	~~Password for the certificate file.~~	❌

Example of the Logging Targets

Logging Targets

This section describes the general and SSL certficate configurations related to IT.

General Configuration

Ensure that the intermediate layer ports are open on the firewall so devices can connect to it.
We recommend that you create a new user to run the Windows Service, which:
- has access to the intermediate layer's folder.
- can read certificates.
- has permission to run a service.

SSL Certificate Configuration

An SSL certificate configuration is only required if the HTTPS protocol is enabled, which is recommended.
If you're not sure how to set up your certificate, contact the IT department.

The following steps require administrator permission.

Open the Certificates snap-in for the Computer account.
The certificate should have a private key. This can be checked when opening the certificate and looking at the bottom of the General tab.
The service owner should have access to the certificate's private key. Move the certificate to the Personal/Certificates folder.
Right click on the certificate and select Manage Private Keys from the All Task menu.
Add the service owner to the list and allow permission for Full control and Read.

Update Steps

Download the new intermediate layer as a NuGet package.
Stop the Windows Service.
Backup the "appsettings.Production.json" file.
Copy and replace the content of the zip file to the intermediate layer's folder.
Merge the old and new "appsettings.Production.json" files.
Start the Windows Service.

Use Multiple Intermediate Layers for the same environment

It's possible to use multiple intermediate layers for the same environment. This can be useful in scenarios where high availability or load balancing is required.

SaaS Configuration For Multiple Intermediate Layers

When utilizing a single CosmosDB instance, no additional configuration is required. Each Intermediate Layer instance can be deployed independently by following the standard setup procedure. If separate CosmosDB instances are used for each Intermediate Layer, it is necessary to synchronize the Encryption Key and Encryption IV across all databases to ensure consistency.

Access the desired CosmosDB instance in the Azure portal.
Navigate to the Data Explorer section.
Expand the "Mobile Solution_Staging" database, then "DatabaseContext," and finally the "Items" collection.

CosmosDB Data Explorer

Identify the following items:

ApplicationSetting|USERSESSIONENCRYPTIONIV
ApplicationSetting|USERSESSIONENCRYPTIONKEY

Select each item to view its details and copy the value from the "Value" field.

CosmosDB Item Value

Open the other CosmosDB instance(s) and navigate to the same location in the Data Explorer.
For both items, paste the copied value into the "Value" field of the target instance and click "Update" to apply the changes.

CosmosDB Update Item

OnPrem Configuration For Multiple Intermediate Layers

When deploying multiple Intermediate Layer instances in an on-premises environment, each instance requires a separate database file. However, to maintain consistency, the Encryption Key and Encryption IV must be identical across all instances. This can be accomplished by initializing the first Intermediate Layer and then copying the "MobileSolution_BusinessData.SQLITE3" file to the directories of the additional instances prior to their startup.

Remote Logging

This feature enables the transmission of logs to the COSMO CONSULT development team to facilitate faster issue resolution. To activate remote logging, set the AllowRemoteLogging environment variable to "true" in the appsettings.Production.json file or within the Azure Web App environment variables. Additionally, the RemoteLoggingTraceRate variable can be configured to send performance metrics, which may assist in optimizing the performance of the Intermediate Layer in future releases.

Status Check

You can verify the status of the intermediate layer by accessing the <IL URL>/core/version endpoint. This endpoint provides information about the current version of the intermediate layer, the supported schema versions, and the service uptime.

Feedback
Submit feedback for this page .

Table of Contents

Intermediate Layer Installation Options

Tip

SaaS Deployment

On-premises

Installation Processes

Requirements

Installation Steps

Logging Options

Basic Logging

Long Term Logging

Description of Environment Variables

Use Multiple Intermediate Layers for the same environment

SaaS Configuration For Multiple Intermediate Layers

OnPrem Configuration For Multiple Intermediate Layers

Remote Logging

Status Check