AMT Deployment Guide
Stephen Fuqua
Ian Christopher (Deactivated)
David Clements
Ben Tillman
Compatibility
The Analytics Middle Tier views support these Ed-Fi ODS database versions:
Ed-Fi ODS / API | Data Standard | Database Engine |
---|---|---|
2.5.1 2.6.0​ | ​2.2 | SQL Server 2016 SQL Server 2017 |
3.1.1 | 3.1 | SQL Server 2016 SQL Server 2017 |
3.3.0 | 3.2a | SQL Server 2016 |
3.4.0 | 3.2b | SQL Server 2016 SQL Server 2017 PostgreSQL 11 |
Suite 3, version 5.x | ODS/API 5.0 to 5.2: 3.2c ODS/API 5.3 to 5.4: 3.3 | SQL Server 2016 SQL Server 2017 PostgreSQL 11 |
Version 6.x | 4.0 | SQL Server 2016 SQL Server 2017 PostgreSQL 11 |
Deprecation Notice
Support for Data Standard v2.2 was removed with the Suite 3 major release. AMT will not longer provide updates to v2.2 after the v4 version of the data standard is released.Â
Preparation
Before beginning the installation, you will need to:
- Select a deployment model, which will determine the correct server and database names to use. The deployment options are:
- Option 1. Installing into a replicated or log-shipped copy of the production ODS database (the generally recommended approach).
- Option 2. Directly installing on your production ODS database.
- Decide which of the optional Collections to install, if any.
- Ensure that the machine running the installation has network access to the database server, and that you can supply database credentials with sufficient access to create new objects in the destination database.
- Review the following documents for awareness of security and performance considerations:
PostgreSQL Tip
We recommend using a pgpass configuration file to store PostgreSQL user password. This approach allows the connection string to contain a database user name without requiring a password.
Installation
While installation of the views is a relatively simple, there are a few steps that need to be followed carefully for a successful and secure deployment:
These are described in more detail below.
Install Options
There are two options for running the installer. The first option is that you can run the installer by downloaded it to your machine or building it from source control. The second option is you can run the installer from a docker container. Both Step 1 options are described below.
Step 1 (option A). Download or Build from Source
- Raw source code (build instructions follow). Can be run from a Linux host.
Download a compiled release in either format:
Binaries for version 2.0.0 and earlier are posted the older GitHub organization, pre-Apache License. To download the binaries, you must be signed in to GitHub with an account that has Ed-Fi licensee access.
EdFi.AnalyticsMiddleTier.zip
 (~2 MB) is a .NET Core framework-dependent deployment, meaning that you must have the .NET Core 3.1 SDK and Runtime installed on the system on which you wish to run the application. Can be run from a Linux host.EdFi.AnalyticsMiddleTier-win10.x64.zip
 (~30 MB) is a self-contained deployment, meaning that you can run it without downloading and installing .NET Core 3.1. Must be run from a Windows host.
Choose an appropriate version, download, and unzip the files.
Step 1 (option B). Run the Installer from Docker
This option assumes you already have a docker environment set up and running. If you don't have a a docker environment, consider using the existing installer in the option A of Step 1. The instructions below use Docker Desktop for workstation usage.  Docker is also available for on-premise and cloud providers as well.
- Images for Analytics Middle Tier (AMT) can be found at Docker AMT Images
To run the installer in Step 2, your installation command will look like:
docker run -t edfialliance/analytics-middle-tier --connectionString "...." --options A, B, C
See Docker Deployment: (Optional) Step 9. Install Analytics Middle Tier for more information.
Step 2. Run the Installer
Command Line Arguments
Command line arguments can be provided using either a "short flag" (e.g., -c "..."
) or "long flag" (e.g. –connectionString "..."
).
Short Flag | Long Flag | Description |
---|---|---|
-c | --connectionString | REQUIRED. Full connection string for the SQL server database on which to install the solution. |
-e | --engine | OPTIONAL. Database engine, either SqlServer  or PostgreSQL  . Defaults to SqlServer . |
-o | --options | OPTIONAL. One or more optional use case collection names, space separated (e.g., The current available options:
|
-u | --uninstall | OPTIONAL. Default: false. Removes all views and indexes, leaving in place the tables configuration tables and roleÂ
|
Running the Tool
The precise syntax for running the tool varies slightly depending on which download and build strategy you have chosen. Examples are shown below for each approach.
Connection String
The connection string will be in standard .NET format, for example:
server=yourServer;database=EdFi_ODS_ReadOnly;integrated security=sspi;
host=yourServer;database=EdFi_ODS_Readonly;username=postgres;
The detailed examples below leave the connection string out in order to focus attention on other elements of the command.
From Source Code
Note that the "long flag" is required for the options when running from source (e.g., use --connectionString
and not -c
):
cd Ed-Fi-Analytics-Middle-Tier\src dotnet run --connectionString "..."
cd Ed-Fi-Analytics-Middle-Tier\src dotnet run --connectionString "..." --engine PostgreSQL
cd Ed-Fi-Analytics-Middle-Tier\src dotnet run --connectionString "..." --options Indexes EWS
Framework-Dependent Download
As with source code, when using EdFi.AnalyticsMiddleTier.zip
you must provide command parameters via the "long flag" form for options.
cd Ed-Fi-Analytics-Middle-Tier\src dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..."
cd Ed-Fi-Analytics-Middle-Tier\src dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..." --engine PostgreSQL
cd Ed-Fi-Analytics-Middle-Tier\src dotnet EdFi.AnalyticsMiddleTier.Console.dll --connectionString "..." --options Indexes EWS
Self-Contained Executable
In this scenario, you can use the long flags as shown above or the short flags as shown below.
cd EdFi.AnalyticsMiddleTier-win10.x64 .\EdFi.AnalyticsMiddleTier.Console.exe -c "..."
cd EdFi.AnalyticsMiddleTier-win10.x64 .\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -e PostgreSQL
cd EdFi.AnalyticsMiddleTier-win10.x64 .\EdFi.AnalyticsMiddleTier.Console.exe -c "..." -o Indexes EWS
Using Docker
In this scenario, you can use the long flags as shown above or the short flags as shown below.
docker run edfialliance/analytics-middle-tier --c "...."
docker run edfialliance/analytics-middle-tier --c "...." -e PostgreSQL
docker run edfialliance/analytics-middle-tier --c "...." -o Indexes EWS
Installing Additional Collections
An administrator can run the installation tool repeatedly with no harm; the install is an idempotent operation. To install additional collections after the initial install, simply re-run the tool and provide the additional collection name(s) at the command line.
Common Errors Seen During Installation
When running the installer in a Non-Windows Environment, such as Linux, MacOS, Windows Subsystem for Linux, or Google Cloud, you could receive the following error:
Error: An assembly specified in the application dependencies manifest (EdFi.AnalyticsMiddleTier.Console.deps.json) was not found: package: 'System.Data.SqlClient', version '4.6.0' path: 'runtimes/unix/lib/netcoreapp2.1/System.Data.SqlClient.dll'
This error comes about due to one of the subfolders that was extracted from the zip file not having the correct permissions. To resolve this you can run the following command from the root of the contents of the extracted zip file:
sudo chmod -R 755 runtimes/*
Once this has been done, then you should be able to run the installer successfully.
Step 3. Configure Database User Access
The installer creates a new security role in the database, analytics_middle_tier
, with permission to query all of the views in the analytics
 schema. The database administrator will need to assign user(s) to this role as appropriate. This can be done by issuing a command like:
ALTER ROLE [analytics_middle_tier] ADD MEMBER [someUserName]
Note that this does not substitute for applying Row-Level Security Collection in the downstream applications. Since the user connecting to the database will have access to all students' data, the end-user application needs to provide its own appropriate row-limiting security features.
Step 4. Configure Descriptor Mappings
The installation process automatically loads descriptor mappings that match up with the default descriptors provided by the Ed-Fi Alliance in the "minimal template" install of the ODS / API. These need to be reviewed and customized for each field implementation.
For detailed information and instructions, please see Descriptor Mapping.
Step 5. Configure Optional Features
Some of the optional Collections have their own configurability mechanisms. Please review and apply instructions from each relevant collection below.
Contents