Appendix A. Sentinet Automated Deployments and Configurations

Sentinet provides command-line utilities, sample scripts and template configuration files to implement automated installations, uninstallations, upgrades and deployments for the entire product or its individual components. Sentinet can be deployed on a stand-alone Windows machine, virtual machine or in a Windows Docker container(s).

Ensuring required Windows OS features and prerequisites are installed
Running Sentinet.msi in a silent mode to uninstall existing installation
Installing Repository Signing X.509, SSL certificate(s) certificate and/or Node identity X.509 certificate
Running Sentinet.msi in a silent mode to install new Sentinet version.
Running RepositoryConfiguration.exe utility in a console silent mode with its configuration file to configure Repository Web application
Running DevPortalConfiguration.exe utility in a console silent mode with its configuration file to configure Developer Portal Web application.
Running NodeConfiguration.exe utility in a console silent mode with its configuration file to configure Node Web application.

Folder C:\Program Files\Nevatech\Sentinet\Samples\Installation contains sample scripts and template configuration files to execute steps listed above. This folder contains two sub-folders, Docker and Scripts. Scripts folder contains files for stand-alone installation and configuration of any or all Sentinet components on a physical or virtual machine. Docker folder contains additional files specific for deployments in Docker containers.

Note

Docker sub-folder contains Install sub-folder with readme.txt file, which must be replaced with those files from Scripts folder that are relevant to the specific component(s) installed in a Docket container (for example, files relevant to Sentinet Node deployment if container is created to host only Sentinet Node).

Sample scripts shipped with the product serve as working examples of executing steps 1-7 described above. Customers can modify existing scripts and/or implement their own approach to executing these steps. The rest of this chapter describes how sample scripts located in the Scripts folder execute steps 1-7 above.

Important

On computer system with default tightened security, automated deployment scripts must be started with run as administrator option.

Prerequisites

Automated Sentinet deployments require Windows PowerShell version 5.1 (PS 5.1), see https://docs.microsoft.com/en-us/powershell/scripting/windows-powershell/install/installing-windows-powershell.

Automated Installation

Before any Sentinet component is fully deployed, Sentinet has to be installed. This process is common to any and all Sentinet components which are being deployed regardless of how many of them will be deployed on a machine or in a Docker container.

Command file C:\Program Files\Nevatech\Sentinet\Samples\Installation\Scripts\Install.cmd starts C:\Program Files\Nevatech\Sentinet\Samples\Installation\Scripts\Install.ps1 PowerShell script. Install.ps1 PowerShell script ensures that:

Required OS prerequisites are enabled and configured.
Previous version of Sentinet (if any exists) is uninstalled.
Current version of Sentinet is installed from Sentinet.msi file in a silent mode.
Sentinet Root CA Signing certificate’s public part is configured in Trusted Root Certification Authorities Windows Certificates Store (optional).

Top part of the Install.ps1 PowerShell script defines few parameters that must be specified before executing script.

Automated Configuration

Automated Configuration process for any Sentinet component, described individually below, goes through the same procedure, which is driven by the content of a single .ini configuration text file.

Command file Config-[component].cmd uses Config-[component].ini configuration file to create and initialize Environment variables from its content. Using Environment variables as an input for the rest of the configuration process is not required, but is a very handy and natural way for passing parameters to Docker-based deployments. Sample scripts shipped with the product, use unified approach for passing configuration parameters for both stand-alone and Docker-based deployments.

Once Environment variables are created and initialized, Config-[component].cmd starts Config-[component].ps1 PowerShell script.
Config-[component].ps1 PowerShell script initializes its variables from the Environment variables and uses its variables to prepare component’s configuration XML file by replacing XML placeholders {…} with the values from the PowerShell variables. Finally, Config-[component].ps1 script calls components’ configuration utility passing to it XML configuration file prepared by the script earlier.

Specific script files for each Sentinet component are described below.

Repository Web Application deployment scripts

Config-Repository.cmd command starts Config-Repository.ps1 PowerShell script. Config-Repository.ps1 PowerShell script uses Config-Repository.ini file and RepositoryConfiguration.exe utility in a console mode along with its configuration XML file. Note, that RepositoryConfiguration.exe utility is the same application that normally runs as an interactive Windows Forms desktop application, while in automated scripts it is started in a console mode using /c command-line argument. You can find all available command-line arguments and samples of their usage by running this application with /c /? command-line arguments:

RepositoryConfiguration.exe /c /?

RepositoryConfiguration.exe with /c parameter can execute complete configuration of the Repository Web Application and Sentinet Repository database creation (or update), or it can execute some stand-alone tasks.

To run RepositoryConfiguration.exe for complete configuration, start it with /c /r /f:[ConfigurationFileName] parameters ,where [ConfigurationFileName] is an XML file that contains configuration settings needed for RepositoryConfiguration.exe application (see Template Configuration file below). To secure information that may be present in [ConfigurationFileName] file, its content can be encrypted. Stand-alone tasks to encrypt and decrypt the content of this file can be executed by running RepositoryConfiguration.exe with /e or /d parameters. If [ConfigurationFileName] file's content is encrypted, it must be used with the encryption password in Config-Repository.ps1 script.

Template Configuration file

Sample RepositoryConfiguration.xml file located in the same folder, C:\Program Files\Nevatech\Sentinet\Samples\Installation\Scripts provides template configuration file for the RepositoryConfiguration.exe application when it is used by the Config-Repository.ps1 script.

RepositoryConfiguration.xml configuration file contains complete (and sometimes redundant) information needed by RepositoryConfiguration.exe utility to execute Repository Web Application’s configuration. The content of the template configuration file contains placeholders which are replaced by Config-Repository.ps1 script prior to starting RepositoryConfiguration.exe utility.

Important

RepositoryConfiguration.exe application can be used in a normal interactive way to create and configure your application, and then to save its input configuration data in XML file. That saved XML file can then be used as a RepositoryConfiguration.xml file which already contains information properly captured for the automated scripts with specific values statically configured in this file.

Automated Deployment with Windows Integrated Security

As described in the Security Deployment Scenarios chapter, the Sentinet Administrative Console can be configured with Windows Integrated security (Sentinet Communication Channel 1, figure 6 in the Security Deployment Scenarios chapter above). Appendix B describes automated scripts that can execute this configuration.

Sentinet Nodes deployment scripts

Deploying and configuring Sentinet Nodes through automated scripts follows similar steps as configuring Repository Web Application, and described above.

Config-Node.cmd command starts Config-Node.ps1 PowerShell script. Config-Node.ps1 PowerShell script uses Config-Node.ini file and NodeConfiguration.exe utility along with its configuration XML file. NodeConfiguration.exe utility is a console command-line utility and does not have /c parameter. It still uses /r parameter but in this case to control Node creation, deletion or update. Note, there is no harm in using /r:create mode instead of /r:update mode as long as create mode is provided enough information in utility’s XML configuration file. You can find all available parameters and samples of the usage by running this utility with /? parameter:

NodeConfiguration.exe /?

To run NodeConfiguration.exe utility for complete configuration, start it with /r:[mode] /f:[ConfigurationFileName] parameters ,where [ConfigurationFileName] is an XML file that contains configuration settings needed for NodeConfiguration.exe utility (see Template Configuration file below). To secure information that may be present in [ConfigurationFileName] file, its content can be encrypted. Stand-alone tasks to encrypt and decrypt the content of this file can be executed by running NodeConfiguration.exe with /e or /d parameters. If [ConfigurationFileName] file's content is encrypted, it must be used with the encryption password in Config-Node.ps1 script.

Template Configuration file

Sample NodeConfiguration.xml file located in the same folder, C:\Program Files\Nevatech\Sentinet\Samples\Installation\Scripts provides template configuration file for the NodeConfiguration.exe application when it is used by the Config-Node.ps1 script.

NodeConfiguration.xml configuration file contains complete (and sometimes redundant) information needed by NodeConfiguration.exe application to execute Node’s deployment and configuration. The content of the template configuration file contains placeholders which are replaced by Config-Node.ps1 script prior to starting NodeConfiguration.exe utility.

Important

NodeConfiguration.xml may need some modification before it is used. Specifically the section below may need to be configured with additional (for example net.tcp) or removed (for example http) protocols before running automated deployment scripts:

<BaseAddresses>
 <BaseAddress scheme="http" host="{env:BASEHOST}" />
 <BaseAddress scheme="https" host="{env:BASEHOST}" />
</BaseAddresses>

Important

Sentinet Node interactive Configuration Wizard (an IIS Manager plug-in described above in this document) can be used to configure your Sentinet Node through a normal interactive process, and then to save its input configuration data in xml file (Configure the Sentinet Node chapter above). That saved XML file can then be used as a NodeConfiguration.xml file which already contains information properly captured for the automated scripts with specific values statically configured in this file.

Developer Portal Web Application deployment scripts

Config-DeveloperPortal.cmd command starts Config-DeveloperPortal.ps1 PowerShell script. Config-DeveloperPortal.ps1 script uses Config-DeveloperPortal.ini file and DevPortalConfiguration.exe utility in a console mode along with its configuration XML file. Note, that DevPortalConfiguration.exe utility is the same application that normally runs as an interactive Windows Forms desktop application, while in automated scripts it is started in a console mode using /c command-line argument. You can find all available command-line arguments and samples of their usage by running this application with /c /? command-line arguments:

DevPortalConfiguration.exe /c /?

DevPortalConfiguration.exe with /c parameter can execute complete configuration of the Developer Portal Web Application and Developer Portal database creation (or update), or it can execute some stand-alone tasks.

To run DevPortalConfiguration.exe for complete configuration, start it with /c /r /f:[ConfigurationFileName] parameters ,where [ConfigurationFileName] is an XML file that contains configuration settings needed for DevPortalConfiguration.exe application (see Template Configuration file below). To secure information that may be present in [ConfigurationFileName] file, its content can be encrypted. Stand-alone tasks to encrypt and decrypt the content of this file can be executed by running DevPortalConfiguration.exe with /e or /d parameters. If [ConfigurationFileName] file's content is encrypted, it must be used with the encryption password in Config-DeveloperPortal.ps1 script.

Template Configuration file

Sample DeveloperPortalConfiguration.xml file located in the same folder, C:\Program Files\Nevatech\Sentinet\Samples\Installation\Scripts provides template configuration file for the DevPortalConfiguration.exe application when it is used by the Config-DeveloperPortal.ps1 script.

DeveloperPortalConfiguration.xml configuration file contains complete (and sometimes redundant) information needed by DevPortalConfiguration.exe application to execute Developer Portal Web Application's configuration. The content of the template configuration file contains placeholders which are replaced by Config-DeveloperPortal.ps1 script prior to starting DeveloperPortalConfiguration.exe utility.

Important

DevPortalConfiguration.exe application can be used in a normal interactive way to create and configure your application, and then to save its input configuration data in xml file (see step 7 of the Developer Portal Configuration chapter above). That saved XML file can then be used as a DeveloperPortalConfiguration.xml file which already contains information properly captured for the automated scripts with specific values statically configured in this file.

Docker Scenario

Introduction

This section describes the scenario in which Sentinet Repository will be configured inside Docker container using environment variables. The scenario also assumes that Sentinet Repository database already exists and was populated.

The tutorial will include the following steps:

Configure installation scripts
Build a Docker image
Run a Docker container

Configure deployment scripts

Basic setup

Sentinet.MSI package installed on a Windows machine provides sample files in C:\Program Files\Nevatech\Sentinet\Samples\Installation folder. Create a new empty folder (for example C:\Sentinet) on a Windows machine that will host Docker containers. Copy entire content of the C:\Program Files\Nevatech\Sentinet\Samples\Installation folder to C:\Sentinet folder of the Docker containers host machine.

Follow instructions from C:\Sentinet\Docker\Install\readme.txt file to prepare scripts and configuration files for Docker container deployment. Copy Sentinet.MSI file to the same C:\Sentinet\Docker\Install folder.

Repository Web Application that will run under IIS server in a Docker container will have to be configured with its SSL certificate. In this scenario SSL certificate will be provided in a PFX file that needs to be prepared and placed in the C:\Sentinet\Docker\Install folder. Note, that in this scenario SSL certificate and Sentinet Repository Signing Certificates will be different. Sentinet Repository Signing Certificates will be auto-generated by the deployment process, while SSL certificate is coming from a PFX file. Note, that certificate should be issued with the Common Name that matched host name or DNS name of a Docker host machine (it can also be a load-balancer or a reverse proxy that stays in-front of a host machine), because Docker container will be accessed via the ports of a host machine (for example, my-host).

You must capture this certificate's file name (for example: my-host.pfx), its PFX password and certificate's thumbprint because they will be used in Config-Repository.ini file as environment variables during the next configuration steps.

Modify Install.ps1 script and Config-Repository.ini files as described below for the deployment scenario covered in this chapter. Note, that only these two files must be modified to implement this specific Docker container deployment.

Install.ps1

Primary functions of Install.ps1 script are:

Installation and configuration of the required Windows Features.
Sentinet installation with provided license key.
Optional installation of provided .cer file ($rootCert variable) of the Sentinet Signing certificate (self-signed certificate) in the container’s Windows Trusted Certification Authorities certificate store. If Sentinet Signing certificate is provided it must be added in C:\Sentinet\Docker\Install folder.

In the scenario we will only provide license key in Install.ps1 file by replacing $Env:LICENSEKEY with the actual License Key value placed in double-quotes, for example:

[string]$licenseKey = “[LicenseKey]”

We will keep $rootCert variable unassigned with the intent to auto-generate Sentinet Signing certificate (self-signed certificate) during the next configuration steps.

Config-Repository.ini

The next step is to edit Config-Repository.ini file. This file contains a list of environment variables that will be used during Docker container creation. This section provides sample values with comments.

CREATENEWDATABASE=false

CREATENEWDATABASE is set to false since the database is already created.

ADMINCONNECTIONSTRING=Data Source=SampleServer;Initial Catalog=master;User ID=user;Password=password

RUNTIMECONNECTIONSTRING=Data Source= SampleServer;Initial Catalog=Sentinet;User ID=user;Password=password

ADMINCONNECTIONSTRING variable defines ASP.NET connection string to the SQL Server master database, while RUNTIMECONNECTIONSTRING variable defines ASP.NET connection string to the Sentinet Repository database.

MONITORINGPARTITIONING=false

Leave this variable with default false value.

CREATENEWMONITORINGDATABASE=false

Leave this variable with default false value since we will not be creating a separate monitoring database.

MONITORINGADMINCONNECTIONSTRING=Data Source=.;Initial Catalog=master;Integrated Security=True

Leave this variable with default or empty value since we will not be configuring a separate monitoring database.

MONITORINGRUNTIMECONNECTIONSTRING=Data Source=.;Initial Catalog=SentinetMonitoring;Integrated Security=True

Leave this variable with default or empty value since we will not be configuring a separate monitoring database.

REPLICATIONLOGIN=

REPLICATIONPASSWORD=

REPLICATIONDATA=

REPLICATIONSNAPSHOT=

REPLICATIONSQLAUTH=

Leave all of the variables from the section above empty since all of them are connected to Optional Monitoring replication configuration element and we will not be configuring a separate monitoring database.

WEBSITE=

WEBSITE value is optional, and is set to empty string since the Repository application will be hosted in the Default Web Site in this scenario. Leave it empty string.

SSLPORTADDRESS=

SSL Port Address is optional and can be left blank.

SSLPORT=8000

We will set TCP Port for SSL binding value to 8000.

SSLCERTIFICATE=CertificateThumbprint

Enter thumbprint of an SSL certificate that is stored in the my-host.pfx file described above.

WEBAPPLICATION=Sentinet

Enter the name of the IIS Application (virtual directory) where Sentinet Repository Web Application will be created (optional). Leave empty string if web application will be hosted in the root of the IIS Web Site.

APPPOOL=DefaultAppPool

Enter the name of IIS Application Pool that Sentinet Repository Web Application will use. Leave it with default DefaultAppPool value.

REQUIRESSSL=true

Enter the SSL requirement for the Web Application. This variable is set to true in our scenario.

SIGNINGCREATENEW=true

SIGNINGCREATENEW is set to true in this scenario, since we want to auto-generate new Sentinet Repository Signing certificate.

SIGNINGCERTIFICATE=

Leave this value empty string for certificate's thumbprint, since SIGNINGCREATENEW=true and new Sentinet Repository Signing certificate will be auto-generated. Set properties for a new, auto-generated Repository Signing certificate.

COMMONNAME=SentinetRepository

DEPARTMENT=Department

ORGANIZATION=Contoso

CITY=Atlanta

STATE=GA

COUNTRY=USA

DAYSVALID=365

Leave variables above with default values, unless you would like to change certificate's properties.

REPORTINGTIMEZONE=Eastern Standard Time

Leave this variable with default Eastern Standard Time, or replace with your time zone name from this list.

REPORTINGTIMEINTERVAL=None

Leave this variable with None value.

ENABLEALERTS=false

Leave this variable with default false value. Since alerts are not enabled in this scenario, all alerts configuration variables below should be left with empty string values.

ALERTFROMNAME=

ALERTFROMADDRESS=

ALERTHOST=

ALERTPORT=

ALERTUSESSL=

ALERTDEFAULTCREDENTIALS=

ALERTUSERNAME=

ALERTPASSWORD=

ALERTCLIENTDOMAIN=

ALERTTARGETNAME=

CREATEADMINISTRATOR=false

Leave this variable with default false value since we are attaching here to existing and populated Sentinet Repository database.

ADMINISTRATORUSERNAME=

ADMINISTRATORPASSWORD=

ADMINISTRATOREMAIL=

Leave three variables above with default empty since we are not creating new Sentinet root administrator account.

INSTALLDIRECTORY=C:\Program Files\Nevatech\Sentinet

Leave this variable with default value C:\Program Files\Nevatech\Sentinet.

CONFIGFILE=RepositoryConfiguration.xml

Leave this variable with default value RepositoryConfiguration.xml, which is the name of the Repository Configuration file located in the C:\Sentinet\Docker\Install folder.

CONFIGFILEPASSWORD=

Leave this variable with default empty string value, since RepositoryConfiguration.xml configuration file is not encrypted with password.

PFXSTRING=

Leave this variable with default empty string value, since we are providing SSL certificate with my-host.pfx file, rather than its base-64 content in this variable.

PFXFILE=my-host.pfx

Enter PFX file name (my-host.pfx) with SSL certificate, which was created earlier in this chapter. In general, there are two options PFX file can be provided for Docker container:

Option 1 -- PFX certificate as a file

Place .pfx file in the .\Docker\Install folder so the configuration process can use it.
Set the PFXFILE variable to the name of this file (e.g. PFXFILE=my-host.pfx)
Leave PFXSTRING value as empty string, it is not needed for this option.

Option 2 -- PFX certificate as a base-64 string

Do not place .pfx file inside .\Docker\Install folder, it is not needed for this option.
Encode your .pfx file's content as a base-64 string.
Set the PFXSTRING variable to this base-64 string value.
Leave PFXFILE variable with empty string value.

PFXFILEPASSWORD=password

Enter the password for SSL certificate in PFX file my-host.pfx.

RepositoryConfiguration.xml

In this scenario RepositoryConfiguration.xml file does not require any modifications since all the needed configuration parameters will come from the Config-Repository.ini file.

Build a Docker image

To build a Docker image, navigate to your Docker directory (C:\Sentinet\Docker in this scenario) and run Build.cmd command file. Note, that this command file uses Dockerfile, which is configured to download Windows OS image for Windows Server 2019, mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-ltsc2019.

When the configuration process is complete, enter docker images -a in Windows PowerShell console to make sure that the image is successfully created.

Run a Docker container

After the image is successfully created, we can run a Docker container based on this image. To run a Docker container, navigate to your Docker directory and run Run-Repository.cmd command file.

When the configuration process is finished, enter docker ps in Windows PowerShell console to make sure that the container is running.

Note

Both Build.cmd and Run-Repository.cmd files are configured with default values such as Docker image name, container name, container host name and port mapping. These values can be edited to receive a different image/container configuration.

At this stage we have successfully configured a Sentinet Repository Web Application inside the Docker container using environment variables.