Project Scope

As a reminder, project Roadrunner is simplified, binary-release of the Ed-Fi ODS/API, targeting both PostgreSQL and SQL Server database engines. This installation provides the following applications:

1. ODS/API with all resources from Ed-Fi Data Standard v3.2, operating in "Shared Instance" mode.
   1. Does not include: extension support; Composites; sandboxes; change queries; profiles.
2. AdminApp
3. /wiki/spaces/ODSAPI33/pages/26443888 (also known as: Client Side Bulk Load)
4. Swagger UI
5. Deployment scripts for deploying the databases and configuring the four applications above.

Operational Requirements

The Roadrunner deployment scripts allow the user to deploy the three Ed-Fi databases (Admin, ODS, Security) to either PostgreSQL or SQL Server. In addition, they download the ODS/API version 3.3 binary release of the API, Swagger UI, and Client Side Bulk Loader, and the current pre-release of Admin App v1.7. After download, the deployment scripts will reconfigure the web.config files by setting up the correct connection strings for the environment, and they will copy the files out to another directory of the user's choosing. These could be network paths for pushing the files out to another web server.

Deployment Server

For the server running the deployment scripts:

• Scripts are built on assumption of PowerShell version 5 or above.
• Requires .NET Core 2.2 SDK
• For PostgreSQL there are two deployment modes, with different requirements:
  • (RECOMMENDED) From source scripts: automatically installs correct version of a custom database deployment tool.

  • From backup files ("templates"): requires psql  executable to be in your command path

    Install via template is primarily intended for cloud environments, where re-packaging might be necessary and the custom deployment tool may be a sub-optimal solution.

    You can install the PostgreSQL client tools locally, which includes psql.exe, from Enterprise DB. While installing you can choose to install only the command line tools without the server, if desired.

• Internet access - this is not an offline deployment process.

Web Server

• Windows 10 Professional or Windows Server 2016+.

• Server role: Web Server. On our integration server we have the following IIS features installed:

   IIS Features ...

  • Common HTTP Features
    • Default Document
    • Directory Browsing
    • HTTP Errors
    • Static Content
    • HTTP Redirection
  • Health and Diagnostics
    • HTTP Logging
    • Logging Tools
    • Request Monitor
    • Tracing
  • Performance
    • Static Content Compression
  • Security
    • Request Filtering
    • Basic Authentication
    • Windows Authentication
  • Application Development
    • .NET Extensibility 3.7
    • Application Initialization
    • ASP.NET 4.7
    • ISAPI Extensions
    • ISAPI Filters
    • WebSocket Protocol
• URL Rewrite module
• .NET Framework 4.8 runtime
• Firewall access from web server to database server, if running on separate servers.
• Does not require MSMQ or .NET Framework 3.5, unlike the full ODS/API release.

Database Server

• Installing SQL Server: both versions 2016 and 2017 have been tested. No testing on 2019 yet.
• Installing on PostgreSQL: final testing performed only on version 11; Beta release was also tested on version 10. No testing on 12 yet.
• Credentials with permission to create and drop databases.

Install Process

1. Download 

Roadrunner binaries and automation scripts are available via a NuGet package. You should download this on your webserver. Two options: NuGet command line or direct download.

This command will automatically unzip the contents into the working directory, under  EdFi.Ods.RoadRunner.1.0.0-rc1 .

Alternately, download from https://www.myget.org/F/ed-fi/api/v2/package/EdFi.ODS.Roadrunner/1.0.0-rc1. This is just a fancy zip file - so if you want to inspect it, just open it with your favorite zip file client.

2. Run Initialize-Environment.ps1

Inside that NuGet package, you'll find Initialize-Environment.ps1 . This orchestration script handles all of the deployment processes described above - installation to either database engine, download of the applications, and setting up connection strings. 

Prepare

In order to run the script, you'll need to have the following information at hand:

1. Database server name
   
   1. In either case, is the database engine running on a non-default port? (1433 for SQL Server, 5432 for PostgreSQL)
      
      
2. Database user credentials
   
   1. If SQL Server, either the deployment account must have admin rights in the database (integrated security), or you need to provide SQL credentials that have admin rights. You can set the password via environment variable $env:SQLSERVERPASSWORD or pass it as a parameter.
   2. If PostgreSQL, then you need to provide database credentials. While the username is passed in as a parameter, the password must be passed through environment variable $env:PGPASSWORD  or, if the client tools are installed, through the pgpass config file.
3. If your PostgreSQL instance requires SSL/TLS encryption, then set environment variable $env:PGSSLMODE="require" .
   
   
4. If installing on PostgreSQL, do you want the standard install or the template-based install? If using templates, you can choose from "empty", "minimal" (includes descriptors), and "populated" (includes a small set of sample data).
   
   
5. If the destination databases already exist, do you want to drop them? ( for PostgreSQL, requires that you have the client utilities installed on the deployment server).
   
   
6. Do you want to change the database names away from the defaults of EdFi_Admin , EdFi_ODS, and EdFi_Security?
   
   
7. Destination folder paths for the four applications:
   1. Web API
   2. Swagger UI
   3. Admin App
   4. API Bulk Loader
      
      

This script has a long list of parameters. It can be useful to create a PowerShell object (dictionary) with the values, instead of trying to string all of the values together in a single command. Doing so makes it easier to review your parameters before running the script.

# Prepare an object dictionary with your parameters
$parameters = @{
   # Add parameters here, e.g.
   engine = "postgresql"
}

# Can also set parameters one-by one
$parameters.databaseServer = "myserver"

# Can review all parameters
$parameters

# Everything look good? Then pass the parameters to the deployment script:
.\Initialize-Environment.ps1 @parameters

Command Syntax and Parameter List

Initialize-Environment [[-swaggerIisFolder] <String>] [[-webApiBaseUrl] <String>] [[-webApiIisFolder] <String>] [[-apiBulkFolder] <String>] [-engine] <String> [-databaseServer] <String> [[-databasePort] <String>] [[-databaseUser] <String>] [[-databasePassword] <String>] [-useIntegratedSecurity] [[-adminDatabaseName] <String>] [[-odsDatabaseName] <String>] [[-securityDatabaseName] <String>] [-useTemplates] [[-odsTemplate] <String>] [-noDuration] [-dropDatabases] [<CommonParameters>]