Content >

Install POS

Download PDF

Install POS

After an EC2 instance has been created using the AWS console, you must login into the instance to configure it and install the Kensium POS server. Login is performed through Windows Remote Desktop (RDP).

You may need to configure a rule for your IP address in the SG-POS-OPS security group for the RDP port to access the EC2 instance. If so, remember to add your name beside the rule to make it easier to update the rule later if your IP address changes.

Important: the POS software introduces fields to Windows Register databases that it needs for operation. The legacy Kensium Comm service, which currently exchanges data between organization locations, expects database tables in each location to have the same fields. To avoid Kensium Comm errors, POS installation and version upgrades should be performed at each organization location within the same timeframe. You can temporarily disable Kensium Comm service while you install or upgrade each location.

As a cloud-hosted POS server can support multiple organizations via multi-tenancy, you must coordinate upgrades across every organization that is represented as a tenant.

a) Connect with RDP

Connect to the EC2 instance using Windows Remote Desktop. Use the Kensium password manager to find the connection information, which should be named to reflect the EC2 instance name (e.g. EC-POS-01 – RDP).

You’ll need the following information to connect:

  • Host name – e.g. POS01.fusionPOS.com
  • User name – Administrator
  • Password
b) Enable Roles and Features

Using the Windows Server Manager, enables the following roles and features:

  • Web Server (IIS) / Web Server
    • Application Development
      • ASP.NET 4.7 (this will enable other services)
      • Application Initialization
      • WebSocket Protocol (for future potential use)
  • Web Server (IIS) / Management Tools
    • Management Service
c) Install Web Deploy

Install Microsoft’s Web Deploy. This will install an extension into the IIS Manager that will enable us to install and update the POS server application.

Web Deploy should add UI options to the IIS Manager to enable you to import and export applications. If for some reason these are not visible, ensure that you have enabled the IIS Management Service described in the previous step.

d) Install ASP.NET Core

Download and install the ASP.NET Core Hosting Bundle.

Version 0.16.0 of POS requires the following hosting bundles:

  • ASP.NET Core version 5.0.11
  • .NET version 5
e) Install SSL Cert

Install the Kensium SSL wildcard certificate into the EC2 instance.

  • The certificate should be installed to the Local Machine / Personal certificate store.
  • Do not mark the certificate as exportable.
  • The certificate (and password) is stored in the Kensium password manager.
  • Use IIS Manager to bind port 443 to the default web application, using this certificate.
  • Use your browser to confirm that the browsing to the site via HTTPS works.
  • Delete the certificate (PFX) file from the server file system once the certificate has been successfully confirmed.
f) Copy POS Install Files

Copy the installation files to the EC2 instance.

  • The installation files should be located in Kensium’s OneDrive files.
  • For example:/!INSTALL/XMS RELEASES/0.16.0/XMS/Kensium.XMS.0.16.0.zip
  • Use the path according to the POS version that you are installing.

Keep the installation file on the server file system – even after installation – as it may be helpful if we ever need to re-install the server.

g) Install POS Application (Setup program)

The POS server can be deployed through an installer, that is located on Kensium’s OneDrive files. This approach is recommended over manual installation.

Run the installer and ensure that you install the software into the correct IIS site. The installer will install both POS Server and the POS Monitor Service.

h) Install POS Application (Manual)

An alternative to deploying POS through the installer program is to manually install. This step and subsequent steps describes the process.

Using IIS Manager, choose Deploy / Import Application.

  • Choose the ZIP file that you uploaded in the step above.
  • When prompted, select all contents of the package.
  • For the application path, you will be installing POS at the root of the site. Ensure this text box is blank and accept the warning that the application will be installed on the default web site.
  • Choose Yes when prompted to delete all extra files.

Important: the initial installation of the POS application is a little different than performing an upgrade. When performing an upgrade, you do not select all content as you do not want to over-write server configuration:

  • You MUST de-select the app_settings.json file and App_Data folder.
  • When upgrading, it’s a good idea to backup this file and folder prior to proceeding, just in case you forget to de-select these items.
  • Choose No when prompted to delete all extra files.

As this is the first time you are installing the application, it is ok to install all items as you will edit them later.

i) Install POS Monitor (Manual)

If deploying manually, you must also deploy the POS Monitor Service executable.

First, copy the Kensium.XMS.Monitor.exe file to the same folder where POS Server is installed.

Then open the Windows command prompt (running as an administrator), and navigate to the folder where you installed the Monitor. Run the following commands to register the service and provide a meaningful description:

> sc create KensiumPOSMonitor binPath= "Kensium.XMS.Monitor.exe" DisplayName= "Kensium POS Monitor" start= delayed-auto

> sc description KensiumPOSMonitor "Monitors the health of Kensium POS server and its active tenants."

Finally, open the Windows Services control panel to verify and configure the Monitor service.

  • Open the Kensium POS Monitor service from the list of available services.
  • Navigate to the Recovery tab.
  • For each of the first, second and subsequent failure actions, select the Restart the Service action.
  • Set the Restart service after field to 1 minute.

At this point, the Monitor service should be configured to run correctly. You can start the service now, or if desired, start it after the rest of POS Server and its tenants are configured.

j) Verify App_Data Folder

Use Windows File Explorer to navigate to the App_Data folder at the root of the web site (usually c:inetpubwwwrootApp_Data).

  • Delete any files and folders contained within the folder. The folder must be empty.
  • Ensure that the folder permissions allow Modify access to the Windows role that ASP.NET and IIS uses to run the site (usually IIS_USRS).
k) Verify Permissions

Use Windows File explorer to navigate to the wwwroot folder at the root of the site (usually c:inetpubwwwrootwwwroot).

Ensure that the the following sub-folders are created, and that the IIS_USRS Windows group has Modify permissions:

  • is_cache
  • ms_cache

This step may be necessary due to a bug in Web Deploy.

l) Create Logging API Key

Login to the Kensium log server (or the QA log server) and create a logging API key for this server. The logging API key should have the following values:

  • Title should be the short host name of the server, e.g. POS01.
  • Leave Permit user access unchecked.
  • Add an applied property named Site (with an upper-case S), and set its value to the short host name of the server, e.g. POS01.
  • Set the Minimum Level to Information.
  • Save your changes.
  • Note the API key; it will be entered in the following step. Do not record the API key elsewhere; if necessary you can always re-generate a new key.

As the logging API key is specified at the server level, the API key (and Site) will be the same for all tenants on the server. POS appends the tenant ID as a Tenant property to every log message to help identify the source of the message.

Avoid using the Debug or (especially) Verbose log levels, except temporarily to track down more information for errors or warnings. These levels generate large amounts of log server traffic and may cause performance issues.

m) Update appsettings.json

Use Windows File Explorer to navigate to the root folder for the site, and edit appsettings.json:

Save the file and restart the web site and application pool.

n) Verify the Site

Use your web browser to connect to the site and verify that it works.

  • The URL should reflect the full hostname of the site, e.g. https://POS01.fusionPOS.com.
  • Verify that HTTPS access is successful without SSL certificate errors.
  • Verify that log server entries are created for the site.
  • Confirm that the Orchard setup page is displayed.