...

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. 

...

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

   Note
   These credentials will be inserted into the web application connection strings. If using integrated security with SQL Server, then be sure to setup the IIS Appol Pool Identity user or the IIS service user, as appropriate, with db_datareader  and db_datawriter access in all three databases.

   
   

   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" .
   If installing on PostgreSQL, do
   1. 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).
   2. If your instance requires SSL/TLS encryption, then set environment variable $env:PGSSLMODE="require" .
      
      
4. Additional database options
   1. 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).
   2. Do you want to change the database names away from the defaults of EdFi_Admin , EdFi_ODS, and EdFi_Security?
      
      
5. 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

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

Parameter List

Examples

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

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

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

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

Only install databases on PostgreSQL, dropping existing database first.

$parameters = @{ 
	engine = "postgresql" 
	databaseServer = "myserver" 
	databaseUser = "postgres" 
	dropDatabases = $true 
}
.\Initialize-Environment.ps1 @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.ps1 @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.ps1 @parameters

3. Setup IIS Applications

If the deployment server is not also the web server, and if your "IIS Folder" paths were local rather than remote, then copy/move the three web application folders to your IIS web server(s). In IIS Manager, setup an Application for each, with custom app pools. If using integrated security in your connection strings, then we recommend setting App Pool Identity as the user and granting that user access rights to read and write in the three remote databases

Running the Applications

Now that everything is setup, you can start using the applications. As a first step, you may want to confirm that the Web API is running. If you installed on server "myserver" with IIS Application named "webapi", then try loading https://myserver/webapi in a browser to confirm that the version endpoint does not generate any errors. If that works, next try https://myserver/webapi/metadata. Any problems? Check the ODS/API error log, which by default is in c:\ProgramData\Ed-Fi-ODS-API.

Before accessing Swagger UI or loading data via the API Bulk Loader, you'll need to generate client credentials (key and secret). If you installed Admin App on server "myserver" with IIS Application named "AdminApp", then try loading htts://myserver/AdminApp. Click through the initial setup, and then stop and restart the web site via IIS Manager to force a security cache refresh.

For more information on Admin App, please see:

• Securing the Admin App
• User Guide

After creating client credentials, you can use them in SwaggerUI or in the API Bulk Loader.

Providing Feedback

Found a bug? 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 deployment scripts? Either file a ticket in Tracker, post a comment below, respond in #dev-roadrunner in Slack, or send email to Vinaya Mayya and Stephen Fuqua.