Operational Requirements

Deployment Automation

• Scripts are built on assumption of PowerShell version 5 or above.
• For PostgreSQL there are two deployment modes, with different requirements:
  • From source scripts: requires .NET Core 2.2 SDK
  • From backup files: requires psql  executable to be in your command path
    • One easy install option: download 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.

Server Environment

• Web Server
  • Windows 10 or Windows Server 2016+.
  • IIS
  • .NET Framework 4.8.
  • Firewall access from web server to database server, if running on separate servers.
• Database
  • SQL Server will work on 2016 and 2017 (untested on 2019, though will probably work).
  • PostgreSQL tested on latest patch releases of 10 and 11, in both Windows and Linux (tested via Docker).
  • Credentials that have the right to create and drop databases.

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-beta1 .

nuget.exe install EdFi.ODS.Roadrunner -Version 1.0.0-beta1 -Source https://www.myget.org/F/ed-fi/api/v3/index.json

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

What's Inside

The repository directories contain various scripts used by the installation process, as well as the compiled binaries for the Web API, Swagger UI, and Api Bulk Loader. The script Initialize-Environment.ps1  is your entrypoint into the installation process.

Installation Process

On the webserver, open a PowerShell prompt and change to the root of the unzipped Roadrunner contents.

Database Security

The installation script has a password flag for SQL Server but not for PostgreSQL, but even for SQL Server it is not recommended. For SQL Server, if you need password security instead of Windows integrated security, then set your password in environment variable $env:SqlServerPassword. For PostgreSQL, either set your password via environment variable $env:PGPASSWORD or use a pgpass.conf file.

If your PostgreSQL instance requires SSL/TLS encryption, then set environment variable $env:PGSSLMODE="require" .

Initialize-Environment.ps1

Installs the Admin, ODS, and Security databases into either PostgreSQL or SQL Server. It then reconfigures the web.config files for Swagger and Web API (both optional) to include the correct configuration for the environment. Finally, loads the bulk console into a destination dir. 

The $useTemplates  flag is currently only available for PostgreSQL. When used, you must have psql  executable in the execution path.

Syntax

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>]

Parameters

Examples

Only install databases on PostgreSQL, using all available default values.

$parameters = @{ 
	engine = "postgresql"
	databaseServer = "myserver"
	databaseUser = "postgres" 
}
 .\Initialize-Environment.psm1 @parameters

Only install databases on PostgreSQL, using templates (populated ODS).

$parameters = @{ 
	engine = "postgresql" 
	databaseServer = "myserver" 
	databaseUser = "postgres" 
	useTemplates = $true 
	odsTemplate = "populated" 
}
.\Initialize-Environment.psm1 @parameters

Only install databases on PostgreSQL, dropping existing database first.

$parameters = @{ 
	engine = "postgresql" 
	databaseServer = "myserver" 
	databaseUser = "postgres" 
	dropDatabases = $true 
}
.\Initialize-Environment.psm1 @parameters

Install databases on SQL Server, with alternate port 1450, and deploy the Web API.

$parameters = @{ 
	engine = "sqlserver"
	databaseServer = "myserver"
	databasePort = 1450
	useIntegratedSecurity = $true
	dropDatabases = $true
	webApiIisFolder = "c:\inetpub\ed-fi\webapi"
} 
.\Initialize-Environment.psm1 @parameters

Install on SQL Server, override the default database, and deploy both the Web API and Swagger UI.

$parameters = @{ 
	engine = "sqlserver"
	databaseServer = "myserver"
	databasePort = 1450
	useIntegratedSecurity = $true
	dropDatabases = $true
	webApiIisFolder = "c:\inetpub\ed-fi\webapi"
	swaggerIisFolder = "c:\inetpub\ed-fi\swagger"
	admindatabase = "edfi_admin_rr"
	odsdatabase = "edfi_ods_rr"
	securitydatabase = "edfi_security_rr"
}
.\Initialize-Environment.psm1 @parameters

Configuration

Web.Config

The web.config files are tuned for the database engine of choice, and tuned to remove features that are not included in Roadrunner. If you wish to switch between providers, you'll need to do so manually or rerun the installation process. To understand the differences between the configurations, you can study the Web.Base.config in comparison to Web.Npgsql.config in the downloaded Ed-Fi-ODS-Implementation\Application\EdFi.Ods.WebApi  folder.

By default, the Web Api application config file will not have a password in it, as password security via pgpass.conf is preferred. However, if you have trouble getting that to work (as we sometimes do), then you can always modify the connection strings manually in your web.config, adding "password=<your password>;" to all three connection strings. Likewise, you may need to set the SSL mode in the connection string.

Key and Secret

The following script will help you create a vendor and application with a pre-defined key and secret, including creating an association with an education organization. Please review carefully and adjust as needed - for example by using some key and secret better than the defaults you'll find in there!

postgres manual vendor setup - Admin.sql

Providing Feedback

Found a bug that is not listed in "Known Bugs" below? Please file a Bug Report in the ODS project in Tracker. Ideally, use "roadrunner" in the labels field and put the name "Roadrunner" in the summary.

Feedback on the delivery? Can file a ticket in Tracker, post a comment below, respond in #dev-roadrunner in Slack, or send email to Vinaya Mayya and Stephen Fuqua.

Known Bugs