UPV WebServices Installation

Installation & Basic Setup

Database

UPV Web Services supports MS SQL Server or Sqlite (restricted feature set without Workflow System).

Database management can be done using a helper tool, called AdminUtil. Execute AdminUtil for a full set of supported commands.

Deploying the database:

Make sure connectionstring and database type are set in sharedsettings.json SQLServer: - Set authentication mode - Create accounts

Execute command:

AdminUtil.exe deploy --createDb -> will create an initial database using specified location in sharedsettings.json .

SqlServer

Necessary configuration steps:

Set server authentication mode to SQL Server and Windows Authentication mode.

The account running the UPV WebServices process (f.e. in IIS) needs full database ownership rights.

Enable FILESTREAM (optional) - Recommended for improving file handling performance. Fallback writes files directly into the database which is inefficient when managing files bigger than about 1.5 MB.

https://docs.microsoft.com/en-us/sql/relational-databases/blob/enable-and-configure-filestream?view=sql-server-ver15

Sqlite

It is possible to use a Sqlite database instead of SqlServer. WorkFlowServer is not supported in Sqlite.
To enable Sqlite edit the sharedsettings.json and add the following line:

"DataBaseType": "sqlite",

UPV WebServices Server

If Installation and Configuration are done, the server is reachable on:
https://systemname/path/signaling (systemname stands for your computer name, your domain or IP address).

Requirements

Hardware minimum:

  • Dual core CPU
  • 8 GB RAM

Supported operating systems:

  • Windows Server 2016 or 2019, Windows 10 1903 or newer
  • Linux (tested with Debian 10)

Installation on Windows IIS

Requirement:

  • IIS with full management
  • IIS WebSocket Protocol

Although the documentation states that IIS Express has WebSockets enabled by default, you should check if this is true.

Go to:
Control Panel / All Control Panel Items / Programs and Features
then Turn Windows Feature on or off, Internet Information Services / World Wide Web Services / Application Development Feature / WebSocket Protocol

Prepare Windows And IIS

Configuration in IIS Manager:

  • Create or ask your IT for a certificate for this system
  • Right click Default Web Site, Edit bindings and add the certificate to the https entry Check that IP Address is “All Unassigned”, otherwise you can access only the URL by host name or IP address

Open the browser and test with the following addresses ““https://systemname”. You should see the IIS start page now.

Prepare Windows For .NET Core: Install .NET Core windows hosting bundle from https://dotnet.microsoft.com/download/dotnet-core/5.0

On the Microsoft page, navigate to the link “Hosting Bundle” as shown below. Don´t click on x86 or x32.

After the installation has finished you have to restart IIS.

Install Files And Create Log Folder

It is assumed that the IIS document root directory has the physical location C:\inetpub\wwwroot and the installation directory is C:\UpvWeb.

  • Extract installation files into folder C:\UpvWeb so that you have a Settings, IdentityServer and UPVWebServices directory.
  • Grant write access on C:\UpvWeb to the user running the IIS e.g. IIS_IUSRS
  • In C:\UpvWeb\UPVWebServices create a subfolder logs and grant
  • Repeat this for C:\UpvWeb\IdentityServer\logs
Prepare Application Pools And Certificate Usage
  • In IIS manager and select Application Pools
  • Create a new application pool with the name UpvWebServices and set .NET CLR version: No Managed Code
  • Create another appication pool with the name IdentityServer and set .NET CLR version: No Managed Code
  • Right click on “Sites / Default Web Site” and select “Add Virtual Directory”
  • Enter “UPVWebServices” as Alias
  • Set the physical path to C:\UpvWeb\UPVWebServices and click OK
  • Repeat this for IdentityServer
  • Right click on “Sites / Default Web Site / UPVWebServices” that you added in the last step and select Convert to Application“
  • Click Select and select application pool UPVWebServices, then press OK
  • Repeat this for “Sites / Default Web Site / IdentityServer” but with application pool IdentityServer
  • Right click Default Web Site / Edit Bindings / https / Edit
    • In Site Bindings the SSL certificate should be selected, then click the View button
    • Go to the Details tab and select the field Thumbprint
    • Select the value and copy it to the clipboard (it’s a 40 character text)

Edit Configuration In sharedsettings.json

Open C:\UpvWeb\Settings\sharedsettings.json in editor.

You need to have Administator privileges to do so.

  • Paste the certificate thumbprint value you have copied in the last step from clipboard as value for key CertificateThumbprint
  • Edit al entries in the ConnectionStrings section to match your SQL Server or Sqlite settings, e.g.
    “UserConnection”: “Server=mysqlserver,1433;Database=myDB;User=UPVWebServicesUser;Password=‘myPassword’;MultipleActiveResultSets=true”,
    ….
  • Edit UpvWebServicesUrl to contain the public host name (not localhost) followed by the virtual directory for UPV Web Services e.g.:
    “UpvWebServicesUrl”: “https://systemname/UPVWebServices”,
  • Edit IdentityServerUrl to contain the public host name (not localhost) followed by the virtual directory for IdentityServer e.g.:
    “IdentityServerUrl”: “https://systemname/IdentityServer”,
  • Edit SignalingServerUrl to contain the public host name (not localhost), the virtual directory for UPV Web Services and a trailing /signaling e.g.:
    [“https://systemname/UPVWebServices/signaling”],
  • Provide a password for Watchdog and UPV in StreamingConfig / SignalingApiCredential, e.g.
    “SignalingApiCredential”: “myNEWcredential”
  • If you want to use a TURN server enter Username and Password
  • Check that the section Serilog / WriteTo / Name/ File / Args / Path points to the logs folder you have create in the previous step above e.g.
    “./logs/upv-service_.log”
Check index.html

Open C:\UpvWeb\UPVWebServices\ClientApp\dist\index.html_ in editor.
Change the base tag’s href attribute from “WFS” to “UPVWebService”:

<base href="/UPVWebServices/">

to contain the correct path to your virtual directory for UPV Web Services.

The trailing ‘/’ is needed!

Ensure Read Access To Private Key

IdentityServer needs acces to the certificate’s private key in order to encrypt access tokens. Thsu ensure

Finish Installation

Restart at least both application pools or IIS.

Open https://systemname/UPVWebServices/ in your browser and you will be redirected to the license activation page.

Special Case: Run More Than One Instance of UPV Web Services

It is possible to run more than one instance of UPV Web Services on the same host under IIS. It is recommended to put them into different subdirectories e.g.:
- C:\UpvWeb\instance1\
contains UPVWebServices, Settings, IdentityServer for instance1
- C:\UpvWeb\instance2\
contains UPVWebServices, Settings, IdentityServer for instance2

Create 4 virtual directories for U We recommend one application pool for each UPVWebServices and each IdentityServer instance.

Install On Linux

Preparations
  • To run the service create a user upvweb1 with group upvwebservices and home directory /srv/upvwebservices/upvweb1.
  • Keep your certificate, private key and certificate password ready. Ensure that upvweb1 has read access to key and certificate file. Alternatively you can use a .pfx file containing both, the cert and the key.
  • Ensure to have 2 ports available which will be bound to UpvWebServices (default 44333) and IdentityServer (default 44358). Take care about unlocking these two ports in the firewall rules!
  • If you are Using A Reverse Proxy, you need to know the base paths that are mapped to both services e.g.
    https://myupvwebservice.com/upv is forwarded to https://localhost:44333 for UpvWebServices
    https://myupvwebservice.com/ids is forwarded to https://localhost:44358 for IdentityServer
    So the endpoints /upv and /ids will be asked.
  • If using MS SQL Server, take care to prepare the database before s. SqlServer. SQLServer, Database name and UPVWebServicesUser’s password are needed during setup.
Installation
  • As root open a terminal window and extract all files to /srv/tmp
  • cd /srv/tmp/linux-x64
  • ./install.sh
Finish Installation

In your browser go to your configured URL e.g. https://myupvwebservice.com/upv/ or https://myupvwebservice.com:44333/ and activate your license.

** The setup writes all entries to /srv/upvwebservices/upvweb1/Settings/sharedsettings.json.** If something went wrong or you need to look up values for configuring the render server, check this file.
See Configuration Details for details.

Configuration Details

Configuration is done in Settings/sharedsettings.json. which can be found in the installation directory.

  • Windows (IIS and standalone): C:\UpvWeb\Settings
  • Linux: /srv/upvwebservices/upvweb1/Settings

Example sharedsettings.json:

{

true indicates running as stand alone web server (Kestrel), false stands for IIS integration.

  "RunAsStandAlone": true,

true will accept invalid certificates. Use this for test environments only!

  "IgnoreCertificateErrors": true,

Show credential informaiton in log file. Use for testing only !

  "ShowPII": false,

Public URL of Identity Server as the user will be redirected to.

  "IdentityServerUrl": "https://myupvweb.com/ids",

Identity Server port if running as Kestrel standalone.

  "IdentityServerPort": 44358,

Public URL of main entry point for UPV Web Services without port. Note that a trailing ‘/’ is needed.

  "UpvWebServicesUrl": "https://myupvweb.com/upvweb/",

UPV Web Services port, only used when running Kestrel.

  "UpvWebServicesPort": 44333,

Path to local file as .pfx or .pem. Either this or CertificateThumbprint has to be set. If a .pem is used, then a key file is needed too.

  "CertificateFilePath": "/srv/mycerts/cert.pfx",

Key file if CertificateFilePath points to a .pem file. Leave this empty if using a .pfx.

  "CertificateKeyFilePath": "/srv/mycerts/key.pem",

Optional password for .pfx or .pem file.

  "CertificatePassword": "Test123!",

Thumbprint for certificate lookup in key store. This is the preferred way when running on IIS.

  "CertificateThumbprint": "",

Additional CORS hosts allowed to be loaded in client browser. Teh specified hosts have access to UPV Web Services in case of own web servers refering to myupvwebservice.com

  "AccessControlAllowOrigin": [ "https://myexternal-web-server.com" ],

(default) or Sqlite.

  "DataBaseType": "Sqlite",

Specify SQL Server, Database, User and Password for database connection.

  "ConnectionStrings": {
    "UserConnection": "Server=mysqlserver,1433;Database=myDB;User=UPVWebServicesUser;Password='myPassword';MultipleActiveResultSets=true",
    "AdminConnection": "Server=mysqlserver,1433;Database=myDB;User=UPVWebServicesUser;Password='myPassword';MultipleActiveResultSets=true",
    "HangfireConnection": "Server=mysqlserver,1433;Database=myDB;User=UPVWebServicesUser;Password='myPassword';MultipleActiveResultSets=true"
  }
}

Define if self service for registration and password reset are allowed.

"AccountManagement": {
  "AllowRegistration": false,
  "AllowPasswordReset": true
},

Section StreamingConfig

List of URLs of BBV server endpoints e.g. https://myhost.com/upvwebservice/signaling. Usually this is one URL but can be extended if external web sites want to embed BBV functionality. Note that they must end with /signaling.

"StreamingConfig": {
  "SignalingServerUrl": ["https://localhost/webupv/signaling"],

Password for server to server API access in Identity Server used by watchdog and UPV.

Do not confuse this with frontend users, that are specified in simpleAuthUsers.json (s. section below).

  "SignalingApiCredential": "myapipassword",

Optional parameter for tuning WebSocket connections. If you notice handshake errors, this parameter defines the timeout in millseconds. Default is 150000, try 2000 - 5000.

  "ConnectionHandshakeTimeout": 0,

Define ICE server settings s. ICE / STUN / TURN.

  "IceConfig": {
    "SdpSemantics": "unified-plan",

One or more URLs to a STUN or TURN server. Most TURN servers listen on different ports and thus need one URL for each. Optional parameter to force TURN (i.e. relay) connections is iceTransportPolicy=relay.

    "IceServers": [
      {
          "Urls": [ "turn:inttu.universalplantviewer.com:443" ],
          "CredentialType": "password",
          "Username": "AskCAXperts",
          "Credential": "ForTestAccount"
      }
      ]
    },

Define model access rules s. Model Role Configuration.

  ModelRoleConfig": { }
},

Section Serilog

See Configuration Basics - Serilog Wiki for more information

"Serilog": {
  "MinimumLevel": {

Set the default log level in MinimumLevel for all output. There are 4 levels:
Fatal, Error, Warning, Information, Debug, Verbose.

    "Default": "Debug",
    "Override": {
      "Microsoft": "Warning",
      "Windows": "Warning",
      "System": "Warning"
    }
  },
  "WriteTo": [

Log to console by default, can be redirected stdout on Linux for example.

    { "Name": "Console" },

Log to file.

    {
      "Name": "File",
      "Args": {

Path can be specified relative the location of the executable.

Ensure that the user running UPV Web Services has write access to the log directory!

        "path": "./logs/upv-service.log",
        "rollingInterval": "Day",
        "outputTemplate": "{Timestamp:u} [{Level}] {Message}{NewLine}{Exception}"
      }
    }
  ]
},

Section ExternalAuthentication

//TODO

To use Google authentication service specify ClientId and ClientSecret.

 "ExternalAuthentication": {
   "AutomaticLoginScheme": null,
   "GroupClaimNames": ["groups"],
   "OpenIdConnectOptions": [
     {

“ServiceConfig” Please leave this as is

Creating Users For Simple Authentication

In Settings/simpleAuthUsers.json you can set up users for testing. These are frontend users that can login and use UPV Web Services. The password policy requires at least one upper case, lower case, digit and special character.

HTTPS / Using Test Certifcates

In order to work properly UPV Web Services has to be set up using secure connections. If using a self-signed i.e. non-trusted certificate, users have to accept this first when navigating to the URL of the UPV Web Services. Depending on the browser, the connection from UPV Web Services Server to Identity Server may be considered as untrusted. To enable using self-signed certificates a work around is implemented to ask the for user to accept the Identity Server’s certificate too before proceeding.

Identity Server usually acts in the background and has limited capabilities to be accessed directly in the browser. To test things like general access you can use the logout page which is always accessible (you will be asked for confirmation before the logout is performed):

https://systemname/IdentityServer/Account/Logout or https://systemname/Account/Logout

Troubleshooting

Troubleshooting For Standalone Version

If starting fails this will be shown in the command window. This open a command window and start from there to avoid closing immediately.

Log files are created with daily rotation under logs as logs/SignalingYYYYMMDD.log. The location of the log file can be changed in sharedsettings.json under “Serilog” / “WriteTo” / “Name”: “File” / “Args” / “path”.

Most critical things to look at first (fix them in system descriptor or local environment):

  • Service or binary not restarted after config changes
  • Port locked by another service or not available
  • Port blocked by firewall
  • identityServer not started although “NoIdentityServer” : false in sharedsettings.json
  • User or password wrong
  • Permissions not granted to dedicated user
  • Wrong path to certificate or key file
  • HTTPS configured without certificate and key file
  • Service has to be restarted after updates to a new version

Troubleshooting For IIS Version

If the process cannot be started by IIS an event is logged in Event Viewer, section Windows Logs / Application. Common problems are:

  • .NET Core Windows hosting bundle not installed or wrong version.
  • Application pools not created or directories not converted to applications.
  • Application pools not recycled after configuration changes. This acts as service restart and needs to be done after any change in sharedsettings.json or in IIS Manager.
  • Wrong format in sharedsettings.json like missing comma.
  • Invisible characters in value of CertificateThumbprint, or wrong thumbprint.
  • SignalingServerUrl wrong in sharedsettings.json.
  • No write access to logs folder. Check if it contains a file like upv-service20210225.log.

If a log file is generated and updated in logs folder, check this to see what went wrong. If nothing helps increase logging by setting minimum level to Debug or even Verbose. You can remove the Override section to see low level logging from web server.

Do not use old Internet Explorer as this is not supported for streaming. Chrome, (New) Edge, Firefox and Safari are fine.

IIS Identity

Most of the tips from chapter Trouble Shooting webupv apply here too.

  • Ensure that the password in simpleAuthUsers.json matches the policy criteria mentioned above
  • Check that the file name is Webupv/Settings/simpleAuthUsers.json and does not contain prefix sample
  • Ensure that all URLs, IdentityServerUrl and SignalingServerUrl, are correct. They are checked sensitively
  • WindowsCryptographicException: Keyset does not exist
    Most probably there are no rights for the IIS user to read the key s. https://github.com/dotnet/aspnetcore/issues/6840#issuecomment-495183563.

Email service

The MailService project is used for sending e-mails issued by the UPV WebServices system (f.e. forgot password, …).

You can either register it as a windows service or start it as standalone application. Configuration of the used e-mail account is done by modifying the sharedsettings.json.

Technical features

Logging

UPVWebServices logging is implemented using Serilog.

You can configure the logging by modifying the sharedsettings.json.

For a documentation of possible logging options see: https://github.com/serilog/serilog-settings-configuration