To install ACP

Introduction

The ACP Server has these software components, also see ACP server Architecture

  • Apache web server to run a websocket connection as a reverse proxy to a nodejs server.
  • The Analytica server - an ACP enabled Analytica process. File name is Suan.exe. The Analytica server process has to be running at all times, and it requires a windows user to be setup with permission to run it..
  • The Analytica session process. Spawned from the ACP server process when you open an ACP session on your browser.
  • Microsoft Sql server (the express version works fine for smaller databases.

Running concurrently with IIS can be problematic, since both Apache and IIS listen to port 80. We recommend not using ACP on a server running a website with IIS.

Configuration files

  • Lumina will send you the Apache ".conf" configuration files for your Apache server separately.
  • Please prepare the following information and send it to Lumina so that we can send you the apache .conf files. (If you are starting up a new server, you need to have completed the server configuration and installation of this software up through the SSL certificates first. )
  1. The Path to and file name for the SSL certificate cert file, the key file and the chain file (if present),eg
C:\Apache24\conf\myservername.com-chain.pem
C:\Apache24\conf\myservername.com-key.pem
C:\Apache24\conf\myservername.com-crt.pem
  1. The server name and domain
  2. The email address of the server admin (optional).
  3. The ip address

Then we will edit the template httpd.conf files and send them back to you, and you can just paste them into the Apache folders as described in the To_install_ACP#Set_up_application_in_Apache_configuration

Add a D: drive

This is optional, but is the default. The D drive is included in the file path in the config files as shipped, so If you change to another drive you will need to edit the file paths here and each time you upgrade to new releases.

  • Create folders D:\Acp\Accounts and D:\Acp\ui

Install software

Apache

C++ redistributables

  • You need to install the Visual C++ 2015-2022 redistributables first available here.

Apache binaries

  • Get the 64 bit Apache package.

Apache no longer provides msi packages for Apache - you have to compile it or get it from a 3rd party.

  • Get the latest 64 bit Apache here.
  • (You can also reference the instructions in the readme file (within the folder when extracting the initial zip archive - not the readme in the Apache24 folder).
  • Extract the zipped archive that you downloaded from apache.
  • Copy the folder Apache24 to the C drive C:/Apache24
  • Test that apache is working - in an elevated command prompt CD to the Apache24/bin folder and enter httpd.exe

(If everything is working there will be no errors and the cursor will sit and blink on the next line).

  • Open a browser to http://localhost - if it's working you should get a web page saying "It works".
  • Exit the command prompt loop with CTRL + C together.
  • Install apache as a service - in an elevated command prompt (if necessary cd to this folder first)

C:\Apache24/bin

  • Then enter

httpd.exe -k install. You should get a message
"The 'Apache2.4' service is successfully installed".
Testing httpd.conf....
Errors reported here must be corrected before the service can be started.
(Assuming there is no list of errors here your install worked.)

  • For now double click the file Apache24/bin/Apachemonitor.exe to continue with setting up and testing the server.

If windows defender prevents this program from starting click the more info link, and click run anyway.

  • Copy or move ApacheMonitor.exe to the start up menu C:\ProgramData\Microsoft\Windows\Start Menu\Programs\StartUp so it starts automatically when the computer starts.

Apache Authentication and PHP

Add a new rule to the firewall

(If you are installing on an intranet - you may also need to open these ports for the server eg Google, Amazon or Azure VM firewalls).

  • Open the windows defender firewall, advanced settings.
  • Select Inbound rules
  • Click “New Rule” on the right-hand sidebar.
  • In the rule type pane, Select “Port,” and click Next.
  • In protocol and ports, select TCP and Select the radio button next to “Specific local ports:” Enter the following into the input box: 80, 443 and Click Next.
  • In the Action pane Select the radio button next to “Allow the connection.” and click next.
  • In the Profile pane "where does this rule apply", Ensure all the boxes are checked, then click Next again.
  • Enter a name for the rule Allow incoming Apache traffic" and click finish.
  • Test if you can access the server from another computer - you should be able to. If you cannot access the server, possibly Apache has turned off. So if this happens, in an elevated command prompt enter C:\Apache24\bin>httpd.exe -k restart.)

SQL server Express

  • If you already have SQL Server installed, you may use your existing SQL server instance.
  • SQL Express works fine for small databases.

Here is a page with instructions and screenshots how to install sql server express

Wait for the installation files to download...

  • In the Sql Server installation center, click the link to New SQL Server stand-alone installation or add features to an existing installation.
  • Note that you need to install the Microsoft Sql Management studio separately now if you choose a custom installation. You can do this by clicking on the link for this in the SQL server installer. You will probably need to launch the installer again after finishing the install.
  • Accept the license and click [Next].
  • Microsoft Updates pane opens - Check the box to use Microsoft Update to check for updates and click [Next]
  • The Install rules pane should show, and should say everything passed except the firewall - I got a warning. Ignore the warning and click [Next] here's an explanation a link to click. .
  • Feature selection pane shows - screenshot shows what I selected

Suanalphawiki07.png

  • Next pane is Instance configuration - accept the defaults and click [Next] and [Next]
  • Database configuration pane - select Mixed Authentication and add a password for the SA user and add any other admins you want, then click [Next], accept the defaults on the other 2 database panes and continue through until finished installation then click [Close]
  • In the Sql Server installation center, click the link to install sql server management tools in the default location.
  • Now, if necessary restart the SQL Server installation center and install Microsoft SQL Server Management studio. Or you could probably just install it from an installer downloaded from Microsoft here
  • Close the SQL server installation center

SSL certificate

  • The SSL certificate needs to be compatible with Apache.
  1. It needs to be a filed certificate - eg not one that is only saved in the certificate store.
  2. Apache requires a PEM encoded certificate, and Apache for windows requires a separate KEY file ( Apache for windows cannot use a certificate file with the key embedded in it as some older systems use. )
  3. There cannot be a passcode embedded in the key.
  4. The certificate must contain the Actual server name eg "myserver.mydomain.com" in the Subject / Common name and/or in the Subject alternative name.
  5. Chrome and Edge browsers now require that any certificate contain a valid subject alternative name, in addition to a valid common name that matches your server name.

Install a free lets-encrypt certificate with win-acme

  • You can install a free SSL certificate from Lets-Encrypt. If you have access to the internet and if your server will allow access to the lets-encrypt verification app. These certificates expire in 90 days, but can be set to automatically renew. Instructions for that are on this page:

Lets-Encrypt Certificate

Enable SSL for ACP

  • Once you have SSL certificates on the server, send the file name and path of the certificate files to lumina, so we can configure the apache .conf files for your server.


We need the Path to and file name for the SSL certificate chain file, the key file and the cert file eg
C:\Apache24\conf\myservername.com-chain.pem (If you have a chain file - depends on the provider)
C:\Apache24\conf\myservername.com-key.pem
C:\Apache24\conf\myservername.com-crt.pem

  • Once Lumina has this certificate information, we will edit the httpd.conf file and send it to you. Save it and continue with the installation steps - you will use them later.

Install the ACP code

  • Download the latest current Analytica release currently

https://downloads.analytica.com/ana/anaSetup6_5_11.exe.

Download the archive and extract it to a folder on your computer.

  • Copy these files (from the archive extracted) to C:\Program Files\Lumina\Analytica 6.4. Overwrite any existing files with the same name.

Analytica.ini
suan.exe
libssl-3.dll
libcrypto-3.dll
SuanFirebaseAuth.dll

The rest of the files from the extracted archive, in folders assets and build, need to saved to the ACP\ui folder.

  • Save these folders to D:\ACP\ui\.

D:\ACP\ui\Assets
D:\ACP\ui\Build

Install support for Publish to Cloud

You can skip this section if the target server does not need to handle "Publish to cloud..." from desktop Analytica.

  • Register the Suan Firebase Auth component:
    • Launch a CMD prompt as administrator
    • CD "C:\Program Files\Lumina\Analytica 6.*"
    • regsvr32 SuanFirebaseAuth.dll
  • Edit the file: assets\PublishServer.config
    • Edit the path for StartupModelFile to point to your assets folder
    • Edit the path for InitialDir to point to the Accounts folder.
    • Ensure DesktopUI=0
    • Take note of the WebSocket port. It should be 8002 -- it will be used in the next step.
  • Edit the apache httpd.config file (probably in D:\Apache2\conf).
    • Go to the bottom of the <VirtualHost> section
    • Make sure these lines are there and uncommented.
# For Publish-to-cloud server in Analytica.
# Include these only if you need to support Publish-to-cloud requests from desktop Analytica.
ProxyPass        "/acp/acpservice.asmx"	"http://localhost:8002/Soap"
ProxyPassReverse "/acp/acpservice.asmx"	"http://localhost:8002/Soap"
ProxyPass        "/acp/client/FileUpload.aspx"	"http://localhost:8002/Upload"
ProxyPassReverse "/acp/client/FileUpload.aspx"	"http://localhost:8002/Upload"
  • Configure the publish service to automatically startup.
    • Launch Task Scheduler
    • Enter Lumina hive
    • Create Task...
      • Name = Serve DTA Publish to cloud requests
      • Change User or Group... to AcpUser
      • Set run whether user is logged on or not
      • Configure for: Windows Server 2022 (I don't think this matters)
    • Trigger tab
      • New.... Begin the task at Start Up.
      • Delay task for 2 minutes
    • Actions tab, New...
      • Program/script: "c:\Program Files\Lumina\Analytica 6.*\Suan.exe"
      • Arguments: /config:d:\acp\ui\assets\publishServer.config
    • Settings tab
      • Allow task to be run on demand
      • Run task as soon as possible after a scheduled start is missed
      • Uncheck "Stop if task runs longer than"

Use different server from desktop Analytica

(This is not a server-side configuration)

As a desktop Analytica user, if you want to publish to a server other than Lumina's main ACP server (i.e., https://acp.analytica.com), then you need to set some registry settings on your desktop computer (not on the server).

To do this, launch RegEdit and navigate to the hive:

HKEY_CURRENT_USER\Software\Lumina Decision Systems\Analytica

Add or modify these values:

  • ACP_AlternateServer: (string) The URL of your server, without leading https://. For example, it might be www.myServer.com
  • ACP_UseSecureHttps: (dword) Make sure it is set to 1 so it uses HTTPS.
  • ACP_AlternateServerPath: (string) /acp/acpservice.asmx
  • ACP_AlternateUploadPath: (string) /acp/client/FileUpload.aspx
  • ACP_AlternateClientPath: (string) /acp/client/acpclient.aspx

Other ACP values may be present, but most will adjust themselves when you use Publish to cloud..

Test this part

  • In D:\Acp\ui\Assets\Session.config, Server.config, and SingleInstance.config files, set, temporarily set DesktopUI=1. Save the files.
  • In a non-admin CMD prompt:
    CD "c:\program files\lumina\Analytica 6.4"
    .\Suan.exe /config:d:\Acp\ui\assets\server.config
    Expected: An Analytica desktop instance should launch with an architecture drawing. It should stick around and not vanish.
  • In Chrome: http://localhost:8080
    Expected: If you are using firebase authentication, Login page should appear. If yuo are using Apache authenticatino, you should be e asked for your user name and password.
  • Once this test succeeds:
  • If you are using firebase authenticaiton, quit all Desktop Analytica instances
  • If you are using Apache authentication, sign in and ensure that you see the acp GUI, with your user name along the top teal bar.
  • Edit both Server.config and Session.config and set:
    DesktopUI=0
    Then save these 2 files.

Add a SQL Server user

  • Launch Start / Microsoft SQL Server Tools 18 / Microsoft SQL Server Management Studio
    • Connect dialog appears.
      Server type=Database engine
      Server name=Yourserver\SQLEXPRESS
      Authentication=Windows Authentication
  • Expand Security / Logins and right click on Logins / New Login
    • General tab
      Login name: SqlAuth
      Sql Server Authentication.
      Enter password.
      Uncheck Enforce password policy.
      Default datase = Suan subscriptions
    • Server Roles: dbcreator, public, sysadmin
    • User Mapping: Suan subscriptons, Master,
      Database role membership for master: DB backup operator, Public
      Database role membership for Suan subscriptions: Public
    • Status: Grant permission, Login enabled

Create the Subscription Database

  • Launch Start / Microsoft SQL Server Tools 18 / Microsoft SQL Server Management Studio
    • Connect dialog appears.
      Server type=Database engine
      Server name=Yourserver\SQLEXPRESS
      Authentication=Windows Authentication
  • Right-click on Databases / New Database...
    • Database name=Suan Subscriptions
    • Press OK

DB Driver info model

  • Edit the model d:\acp\ui\assets\db driver info.ana
  • Enter the SQL User name and SQL password, then save the model. Close the model

Use the Analytica library to create the tables in the database

  • Run: Analytica.exe "d:\Acp\ui\assets\Create Suan DB.ana"
  • Press the "Create the Tables" button
  • Press the "Populate the Tables" button

Set up application in Apache configuration

  • In the Apache\conf directory, rename the default httpd.conf file to httpd-bk.conf so you have it as a backup, then replace it with the httpd.conf file you received from Lumina.
  • In the Apache\conf\extra directory, rename the default httpd-ssl.conf file to httpd-ssl-bk.conf so you have it as a backup, then replace it with the httpd-ssl.conf file you received from Lumina.
  • Check the apache configuration - in an administrator command prompt

cd C:\Apache24\bin

httpd.exe -t

{Output should be syntax OK} If not then there is a problem .

  • If the response is OK, restart apache in the command prompt:

cd C:/Apache24/bin
httpd -k restart

  • Test
    • Open a non-admin UI CMD window:
      CD "C:\Program Files\Lumina\Analytica 6.4"
      .\suan.exe /config:d:\Acp\ui\assets\server.config
      Expected: No UI appears. But in Task Manager, you should see a Suan process running.
    • In a browser on the server: Check your url
      Expected: The login page appears. Tests for apache & UI-side code working.
    • Log in - enter an email address and password and press Sign up.
      Expected: Goes to User Portal, with an empty file listing.
  • On a computer other than the server, in Chrome: Check your url with https
    Expected: Should get to login screen
  • On a computer other than the server, in Chrome: Check your url with http
    Expected: It should convert to https and be an the login screen

Setup account to serve requests

We create a new account with security restrictions that ACP requests (i.e., models) run under.

  • Run Computer Management / System Tools / Local Users and Groups / Users
  • New User...
    User name = ACPUser
    Description = Account that ACP models run in.
    Password = ***yourpasswordhere***
    User cannot change password + Password never expires
  • Press Create. Then Right-click ACPUser/ Properties / MemberOf. Remove from group "Users".
  • In a CMD prompt:
    CD "C:\Program Files\Lumina\Analytica 6.4"
    RunAs /user:ACPUser .\Analytica
  • When Analytica launches, accept the terms and select the license in Desktop Analytica's Help->Update License dialog
  • Test that it saves this info by exiting and restarting, again as ACPUser, and checking the Help-Update License dialog.

Note -- To launch the server now, from CMD, use:

RunAs /user:ACPUser "c:\Program Files\Lumina\Analytica 6.4\Suan /config:d:\Acp\ui\assets\server.config"

Configure for auto-launch

Configure Windows to automatically launch the Suan server when the computer boots.

  • Run Task Scheduler
    • Create a new folder under "Task Scheduler Library" named Lumina
    • Right-click on Lumina / Create Task...
    • General tab
      Name: Start ACP server0 at boot
      Description: Launches the ACP server process when the server starts up (reboots)
      Press "Change User or Group..." and set to ACPUser
      Run whether user is logged on or not
      Configure for: Windows Server 2019 (I don't think this matters)
    • Trigger tab
      New.... Begin the task at Start Up.
      Delay task for 30 seconds
      Repeat task every 59 minutes
    • Actions tab, New...
      Program/script: "c:\Program Files\Lumina\Analytica 6.4\Suan.exe"
      Arguments: /config:d:\Acp\ui\assets\Server.config
    • Settings tab
      Allow task to be run on demand
      Run task as soon as possible after a scheduled start is missed
      Uncheck "Stop if task runs longer than"
      If the task is already running, Stop the existing instance
    • Create 2 more tasks for the server1.config and server2 config. Same except the name / Arguments and Delay for 60 seconds and 90 seconds, repeat every 57 and every 53 minutes

Add permission for log on as a batch job

  • At Start menu, type: "Local security policy"
    • Drill down to: Local security policy / Security Settings / Local Policies / User Rights Assignment / Log on as a batch job / Add User or Group...
    • Add ACPUser [Apply] [Ok]
  • Test that the new task works by
    right-clicking on the Task Scheduler task added above / Run.
    Task manager / Details. Verify that Suan.exe is running under the ACPUser account.

Create a Group Account

So now you should be able to use ACP. Here we will create a Group account with 1 admin user. The admin user will need to verify their email address and create a password, so it needs to be someone who will be watching their inbox.

  • Copy these files

d:\acp\ui\assets\suan account admin.ana
d:\acp\ui\assets\db driver info.ana
d:\acp\ui\assets\database.ana
to:
d:\acp\accounts\suan account admin.ana
d:\acp\accounts\db driver info.ana
d:\acp\accounts\database.ana

  • In a command prompt

cd c:\"Program Files\Lumina\Analytica 6.4"
.\suan.exe /config:d:\acp\ui\assets\singleinstance.config "d:\acp\accounts\suan account admin.ana"

When prompted to create a subscription administrator, click yes.

  • Open the module Create new Group Subscription.
  • In the account type select Group or Premium Group - if you are installing with optimizer select Premium Group
  • Enter a Account/Subscription name

{If you are using the firebase authentication - the default.}

  • Enter an email address for the Group account admin (needs to be someone who can open the email inbox)

(If you are using Apache authentication with sspi - windows authentication with windows user names. Enter the windows user name for the Group account admin instead). (If you are using Apache authentication with apache password file.authentication. Enter the Apache user name for the Group account admin instead).

  • Press the [Create Subscription] Button

Expected: You should get a message box 'Subscription created'. Clear that by Clicking [OK]

  • Close the module Create new Group subscription and open the module Manage existing Group subscription
  • In the pulldown menu for Subscription Admin, ensure that the new user is selected as the subscription admin.
  • Close the suan account admin.ana model for now.

Expected: You should have a group account that you can use with ACP in a browser. And the subscription manager is the user whose email address you entered

  • Go to the ACP sign in page (your domain) in a Chrome Browser. (For now we are recommending that users stick with Chrome until we have done more testing in other browsers).
  • In the email field enter the email address for the Group account admin
  • You need to get a password unless you already have one for this firebase account - click the link get a new password. Should get a message that a password reset email has been sent to the email address.
  • Now open the email inbox for the Group account admin and click on the password reset link.
  • Enter a password and press Save. You should now be able to sign in to the Group account.
  • Go back to the ACP sign in page and enter this password in the password field then press sign in or enter

Expected: You are signed in to ACP with the your Account name in the Account pulldown menu and the Home Project.

That's it . You can upload models, add users and projects now. You can also manage subscription admins. See more here.

Note - you can also create individual accounts by going to the sign in page, entering an email address and password, then pressing Sign up. Currently you cannot create an individual account if the user is part of the Group account.

Configure database backups

SQL Express Database Backups

If you don't have another backup system for your server, we recommend you set up a scheduled database backup for your Suan Subscriptions database. These instructions will backup your database once daily, with the date appended to the file name so the previous backups don't get overwritten.

  • Create the directory C:\BKSQLDBS
  • Find the port SQL EXPRESS is listening on - it will be dynamic, but should stay the same as long as the port is available.
  1. Open SQL SERVER Configuration Manager
  2. Select SQL SERVER Network Configuration /Protocols for SQLEXPRESS
    1. TCP/IP (ensure it is enabled)
    2. Double click TCP/IP
    3. Select the IP Addresses tab
    4. Scroll down to IPALL - TCP\Dynamic ports (note the port number )

If there is no port number here, ensure TCP/IP is enabled as in step 2, close the SQL Server Configuration Manager, Close SQL Server Management studio if open, and restart the SQL Server (SqlExpress) service. Then reopen the SQL Server Configuration Manager and check the port again.

  • Open task scheduler
  • Create task -> general Tab
  1. Description: Backup Suan subscriptions database, Run whether user is logged on or not, Run with highest privileges, Configure for windows 2019
  2. Triggers - Daily at 8:00 AM
  3. Actions
    1. - Start a program, Program/script: "C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\SQLCMD.EXE"
    2. Add arguments: -S SUAN-ALPHA\SQLEXRESS,60917 -E -Q "DECLARE @fileName NVARCHAR(512) DECLARE @fileDate NVARCHAR(40) SELECT @fileDate = CONVERT(NVARCHAR(20),GETDATE(),112) SET @fileName='C:\BKSQLDBS\suandatabsebk' DECLARE @File NVARCHAR(512) SET @File=@fileName+@fileDate BACKUP DATABASE [Suan Subscriptions] TO DISK=@file" (Replace SUAN-ALPHA\SQLEXPRESS,60917 with your SQL instance name from the SQL Server Management studio, and the TCP port number your SQLEXPRESS instance is listening to. )
    3. Start in: C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn\
    • Conditions: Clear all checkboxes
    • Settings: Allow task to be run on demand, Stop if it runs longer than 1 hour, If it does not end force it to stop
  • Save the task
  • Run the task to see if the backup gets saved

Set the timeout for ODBC error messages.

If you have a large number of concurrent sessions, the database connection may time out. There will be an on screen error message starting with ACP 3.1. Build 119. To make this less likely you can set the timeout to longer than the default 10 seconds with this registry setting:

In HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/6.4
Create the DWORD OdbcLoginTimeout=60 and
DWORD OdbcConnectionTimeout=30

Set Maximum memory use (Optional)

If you need to control the maximum memory (RAM) per instance of Analytica you can do this with registry settings. Working_Set_Size
This will control the RAM use per session but not the paging file usage so the total memory can be much higher. If you have a very large model you may want to consider a very large paging file. In HKEY_LOCAL_MACHINE/Software/Lumina Decision Systems/Analytica/6.4

  • Create a new DWORD WorkingSetMax and enter the desired decimal value in MB. EG 6000 to set the max of 6GB.
  • Create the DWORD and set the WorkingSetFlags to 4 - Hard max

Add Spreadsheet functionality with LibXL

{Optional}

  • If you want to use libXL for spreadsheet access from ACP, you can add this to your server. Follow the instructions here.

Configure a sub folder that can be read with a public URL

{Optional}
For an ACP server. To add a public folder to an ACP project for downloading data files written by ACP. Add a public folder to ACP


See Also

Comments


You are not allowed to post comments.