Installation Guidelines

Introduction

Aucerna’s portfolio optimization and stochastic analysis software.

Optimization

Given a list of opportunities, metrics and constraints, Aucerna Portfolio performs a portfolio optimization to answer how much of which opportunities should be done, and when.

The optimization is controlled by:

• What we want to maximize?
• What we want to achieve?
• What constrains us?

Stochastic analysis

Monte Carlo simulation is used to build a statistical description of the portfolio’s result. The range and shape of the possible outcomes can then be analyzed providing critical insight into the uncertainty profile of the portfolio.

With Aucerna Portfolio through optimization and uncertainty analysis the user can understand and leverage interactions between goals and opportunities, characterizes aggregate business performance, risks and uncertainty, understand impact of constraints, analyzing impact of decisions. In summary, the user can interactively interrogate your data to optimize strategy, maximize value and understand risk.

Installation Prerequisites

Aucerna Portfolio is a web delivered application using a Service Oriented Architecture (SOA). It requires one or more application servers with a SQLServer database for data persistence. The general specs for the servers are proved below as well as any pre-requisites for installation. The Application servers can be made into a cluster if the user base and redundancy of the system require it but that is not covered in this document.

Recommended Hardware

• CPU: Intel i7, Intel Xeon E5, or AMD Opteron 6000 series with at least 8MB of L3 cache
• RAM: Minimum: 16 GB for simple scenarios. Recommended: 128 GB for more complex scenarios.
• Storage: 256 GB (200 GB partition for the OS and 56 GB partition for the application)
• Cores: At least 8 (with an additional 2 cores for each concurrent optimization over 4)

Software

• OS: Windows Server 2016 or newer.
• DMS: Microsoft SQL Server 2016 or newer.
• Web Server: Microsoft Internet Information Services (IIS) — included in Windows Server
• License Manager: RLM server (only necessary if client has a counted user license)

Application server

• Windows Server based (2016 Server or better)
  • It is recommended that a minimum of 8 cores be allocated with 2 additional core for every 2 users over 4. Aucerna Portfolio uses multi-threading so additional cores can improve performance of the calculations.
  • It is recommended to allocate 32 GB of memory plus an additional 8 GB of memory for every 4 concurrent users above 4.
  • 200 GB partition for the OS and 56 GB partition for the Application.
• .NET Framework v4.6 or later
• IIS with the following features enabled
  • Web Server
    • Common HTTP Features
      • Default Document
      • Directory Browsing
      • HTTP Errors
      • Static Content
      • HTTP Redirection
  • Health and Diagnostics
    • HTTP Logging
  • Performance
    • Static Content
    • Dynamic Content
  • Security
    • Request Filtering
    • URL Authorization
    • Windows Authentication
  • Application Development
    • .NET Extensibility 4.5
    • ASP.NET 4.5
    • ISAPI Extensions
    • ISAPI Filters

• Management Tools
  • IIS Management Console
• An SSL certificate securing IIS
• URL rewrite module 2
• LindoAPI 9.0 64-bit (Aucerna Portfolio optimization engine) installed with a proper license (Lindo Install and license provided with esi.portfolio).
• Aucerna Portfolio hosting server specific license (Issued by Aucerna based on the host id)

Database Server

• Windows Server based (2016 Server or better)
  • 4 cores with an additional core for every 5 users.
  • 256 GB HD for OS and additional 256 GB HD for a data partition (This may need to grow depending on usage).

• SQL server 2012 or later with Mixed Authentication Mode enabled

Architecture

Click image to expand or minimize. 

Click image to expand or minimize. 

Data Center

Hosted in Calgary at Q9 (www.Q9.com )

• 24/7 Physical Security
• Redundant Internet
• Uninterruptable Power Supply
• Fire Suppression
• Two separated data centers (12km apart)
• Cross DB backups between Data Centers.

Quickly recreate hosted environment in alternate Data Center and restore DB backup

First-Time Installation

This is only needed the first time around, after that these settings/changes should not be required unless moving to a new set of servers.

Create root directory for the website files

• Location of your choosing.
• Referred to as WEBROOT in this document.

Create subdirectories for the web applications

1. WEBROOT\web-api
2. WEBROOT\gui-app

Set up IIS

1. Create an Application Pool:
   • Name is arbitrary; Aucerna Portfolio preferred.
   • .NET Framework Version must be set to (at least) .NET Framework v4.0.30319

2. Create a new web site/web application for gui-app:
   • Site name, path, and/or alias are arbitrary
   • Application Pool: The application pool you created above
   • Physical path: WEBROOT\gui-app

3. Create a new web application for web-api as a child of gui-app:
   • Alias: api
   • Application Pool: The application pool you created above
   • Physical path: WEBROOT\web-api

4. Configure SSL:
   • This is optional but recommended for most installations.
   • See https://msdn.microsoft.com/en-us/library/hh556232(v=vs.110).aspx
   • If you are redirecting HTTP URLs to HTTPS (see below), then you do not have to check the "Require SSL" checkbox on the "SSL Settings" pane. (Step 3 in "Configure Virtual Directory for SSL.")
   • Note that there are SSL-specific settings in Web.config that are discussed in the section on configuration.

5. Install the Microsoft IIS URL Rewriting Module:
   • This is optional but recommended for most installations.
     • If you're using SSL/HTTPS, it's beneficial to automatically redirect HTTP URLs to their HTTPS equivalents.
   • Download from:
   • http://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads
   • Note that there are URL-rewriting settings in Web.config that are discussed in the section on configuration.

Set up Microsoft SQL Server

1. Create a new MSSQL database:
   • Name is arbitrary; Aucerna Portfolio preferred.
   • Database file paths are arbitrary
   • No known dependencies on other settings

2. Create a database login (if necessary):
   • Nothing stopping re-using an existing user.
   • While we generally use logins with SQL Server Authentication, it is possible to use ones with Windows Authentication
     • Note that, to use Integrated Security, the IIS Application Pool will need to authenticate to MSSQL with the login. See this Stack Overflow answer for instructions on how to create a MSSQL Login with the identity of an IIS Application Pool.
   • The login does not need to be granted any server roles (besides public).

3. Map the login to a user in the new database and grant permissions:
   • default schema: dbo
   • Database role memberships: db_owner (and public)

Set up licensing

1. Acquire the Aucerna Portfolio license file (filename ending in .lic).
2. Copy the license file to a convenient location:
   • The location is arbitrary
   • Keeping it outside of WEBROOT\web-api is advisable, as these files might need to be replaced during upgrades
   • We recommend placing it in WEBROOT

Deployment/Upgrade Steps

1. Acquire a copy of the Aucerna Portfolio zip files:
• Choose the appropriate build project.
•  Under "Last Successful Artifacts", download both zips
  • web-api*.zip
  • gui-app*.zip
2. Review the release & upgrade notes for your particular copy.
3. Extract gui-app*.zip to WEBROOT\gui-app
4. Extract web-api*.zip to WEBROOT\web-api
   • Be on the lookout for locked files, particularly bin\rlm1102.dll.
     • You may need to stop and start the IIS Application Pool to unlock this file
5. If necessary, perform configuration as described below.
6. Recycle the IIS Application Pool.

Configuration

The first time you install the application, you must perform these configuration steps. Thereafter, upgrading the application will generally not require reconfiguration, so you can and should skip these steps. However, changes to the local configuration may be required even when upgrading an existing installation; see the release and upgrade notes for details.

Set up Web.config

1. Copy WEBROOT\gui-app\web.sample.config to WEBROOT\gui-api\web.config.
2. Changing settings for the web site/application will modify this file.
3. The <mimeMap> tag which maps .json to application/json should be commented out.
4. The settings in the <authorization> tag are reasonable defaults, but can be modified; see below for details.
5. There is a <rewrite> section that redirects all HTTP URLs to their HTTPS equivalents. If you are not doing HTTP->HTTPS redirection than you can remove/comment out this section; it's not required for the app to function.

6. Copy WEBROOT\web-api\Web.sample.config to WEBROOT\web-api\Web.config.
   • This file contains many settings that are critical for the application to run successfully. It's important to preserve most of it as-is.
   • Changing settings for the web application will modify this file.
   • Generally, this file shouldn't need to be modified except for adding the globalization option:
     • In section <system.web> :

     

• The web-api web application inherits its authorization settings from its parent gui-app.
  • The sample config file assumes that the app is running under SSL/HTTPS.
    • Specifically, the attribute at bindings/webHttpBinding/security/@mode must be set to "Transport" when using HTTPS.
    • If you're not using HTTPS, set the mode attribute of the security element to "TransportCredentialOnly".

7. Copy WEBROOT\web-api\Web.Release.sample.config to WEBROOT\web-api\Web.Release.config.
8. Copy WEBROOT\web-api\Web.Debug.sample.config to WEBROOT\web-api\Web.Debug.config.

Set up AppSettings.config

1. Copy WEBROOT\web-api\Configuration\AppSettings.sample.config to WEBROOT\web-api\Configuration\AppSettings.config.
2. Modify AppSettings.config:
   • Set LicenseFileLocation to the path to the Aucerna Portfolio License file (see above).
   • UseInprocEventTracing, UseDatabaseLogging, and EventKeywords, and OptimizationEngine may be modified during error investigation, but generally should be left as-is.

Set up Database.config

1. Copy WEBROOT\web-api\Configuration\Database.sample.config to WEBROOT\web-api\Configuration\Database.config.
2. Modify Database.config:
   • Must contain a connectionString for the key PrismDbContext.
   • The sample connection string is appropriate for:
     • a MSSQL instance named SQL2012.
     • running on the same system as IIS.
     • using a Login named esi.Portfolio-user.
     • with SQL Server Authentication and a password of esi.Portfolio-user-password
   • Modify the connection string to fit the database configuration:
     • MultipleActiveResultSets=true must be preserved.

Set Up EntityFramework.config

1. Copy WEBROOT\web-api\Configuration\EntityFramework.sample.config to WEBROOT\web-api\Configuration\EntityFramework.config (no modifications necessary).

Update IIS Authentication

• Authentication should be set on the gui-app web site/application and inherited by the web-api web application.
• Windows Authentication must be enabled
• Anonymous Authentication must be disabled

Update IIS Authorization Rules

• Authorization should be set on the gui-app web site/application and inherited by the web-api web application.
• The sample authorization (set in gui-app\web.config.sample) is a good starting point, but can be customized for the installation environment
• Must have a Deny: Anonymous Users rule.
• Must have some sort of Allow rule. Allow: All Users and Allow: Roles: Aucerna Portfolio are common.

Ensure that the IIS Application Pool has write permissions to the log director

• The log directory is set in WEBROOT\web-api\Configuration\AppSettings.config, at theLogDirectory` app setting value.
• Generally, you want to grant Write permission on the directory to the user IIS APPPOOL\[app pool name]
• For more details see: http://serverfault.com/questions/81165/how-to-assign-permissions-to-applicationpoolidentity-account

License Management

This section describes the license Management structure.

• The license should be located in its own folder, called License.

Production Database Migration/Initialize

This section describes how the database is configured the very first time. This should only be done on the initial install or when a major release update requires this.

1. Migrate.exe is located in web-api\bin:
   • Modify migrate.exe.config to point to the database. The tool can also create a new database.
   • Open up a command prompt window, and run migrate-db.bat.

To initialize the database for a NEW instance, follow these steps:

1. Open the EntityFramework.config file.
2. On the line that has this text "disableDatabaseInitialization" change the flag to false.
3. This will tell the database to start getting configured.
4. Browse to the web-api --> bin.
5. Shift – RIGHT Click. And open a command prompt window here.
6. Run the Migrate-DB.bat file (this file will setup the database for you).
7. Once it is complete check the migrate-db.log file to make sure there are no weird errors.
8. Go back to the EntityFramework.config file.
9. On the line that has this text "disableDatabaseInitialization" change the flag to true.

Upgrade to the Latest Version

This section describes the steps require in upgrading the Portfolio install to the latest version.

When you receive the latest version, do the following steps to update Portfolio to the latest version.

1. On the server where Aucerna Portfolio is hosted, stop the IIS server.
2. Ensure that the database has been properly backed up.
3. On your local computer download whichever version that they want (ie. Nightly, Master...).
4. Copy that to the server.
5. Rename the gui-api and web-api folders, to GUI-API-BAK and WEB-API-BAK. This is done to allow you roll back to the previous release.
6. Extract the new builds to gui-api and web-api respectively.
7. Copy the configuration files from GUI-API-BAK to gui-api, and from WEB-API-BAK to web-api.
8. Start the IIS server.
9. Open the web browser to the website where the portfolio application is installed.