Installation Guidelines

Installation Prerequisites

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. 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 (Portfolio optimization engine) installed with a proper license (Lindo Install and license provided with esi.portfolio).
  • Portfolio hosting server specific license (Issued by Quorum 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; Portfolio preferred.
    • .NET Framework Version must be set to (at least) .NET Framework v4.0.30319
  1. 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
  1. 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
  1. Configure SSL:
    • 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.")
  1. Install the Microsoft IIS URL Rewriting Module:

Set up Microsoft SQL Server

  1. Create a new MSSQL database:
    • Name is arbitrary;Portfolio preferred.
    • Database file paths are arbitrary
    • No known dependencies on other settings
  1. 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).
  1. 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 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 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 and 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.
  1. 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".
  1. Copy WEBROOT\web-api\Web.Release.sample.config to WEBROOT\web-api\Web.Release.config.
  2. 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 thePortfolio 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: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 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.