Changes since Beta 1

• Using the same ODS/API code as recently released for version 3.3 (thus the ODS/API at "production quality")
• Supports Data Standard 3.2
• Admin App now included.
• Improvements to the deployment scripts. From end-user perspective, the primary change is to download previously-packaged versions of the web applications instead of re-compiling and re-packaging them.
• No longer testing on PostgreSQL 10, now that all three cloud providers support PostgreSQL 11.

Project Scope

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

1. ODS/API with all resources from EFDS32, operating in "Shared Instance" mode.
   1. Does not include: extension support; API Composites; sandboxes; change queries; profiles.
2. AdminApp
3. /wiki/spaces/ODSAPI33/pages/26443888
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) on a PostgreSQL database 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

• Requires the command line tools from PostgreSQL 10 or 11, with psql.exe  in your command path.

  Expand
  title Installing PostgreSQL tools...
  Download the 11.5 release from Enterprise DB (Windows x64 edition). Run the installer. When the installer gets to the point of selecting components, you can deselect the Server and Stack Builder options. pgAdmin4 is optional; it is a versatile GUI tool for managing your server, with the drawback that it cannot open or save SQL files. When the installation is complete, edit your path by adding C:\Program Files\PostgreSQL\11\bin (assuming you installed the x64 edition).

  
  

• 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:

  Expand
  title 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 PostgreSQL 10.x or 11.x. This release candidate was only tested on version 11.5; however, the beta release was also tested on version 10. No testing on 12 yeta 10.x database, and no version 11 features have been used.
• Credentials with permission to create and drop databases.

create role postgres NOINHERIT;
grant postgres to edfi;

Install Process

1. Download NuGet Package

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 .

Install Process

1. Download NuGet Package

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 .

nuget.exe install EdFi.ODS.Roadrunner -Version 1.0.0-rc1 -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-rc1. This is just a fancy zip file - so if you want to inspect it, just open it with your favorite zip file client.

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. 

2. Run Initialize-Environment.ps1

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

   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 Appl Pool Identity user or the IIS service user, as appropriate, with db_datareader  and db_datawriter access in all three databases.

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

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.
If installing on PostgreSQL
4. 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).
If your instance requires SSL/TLS encryption, then set environment variable $env:PGSSLMODE="require" .
Additional database options
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).
Do you want to change the database names away from the defaults of EdFi_Admin , EdFi_ODS, and EdFi_Security?
Destination folder paths for the four applications:
6. Web API
7. Swagger UI
8. Admin App
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.

1. 1. While the username is passed in as a parameter, the password must be passed through environment variable $env:PGPASSWORD  or a pgpass config file.
      
      

2. Choose a template
   1. Empty: contains no data.  Not recommended as getting initial key/secret and descriptors setup is challenging.
   2. Minimal: contains default descriptors, making it possible to setup new education organizations and to create a client key and secret.
   3. Populated: contains a small set of sample data, in addition to the descriptors.
      
      
3. Additional database options
   1. If your instance requires SSL/TLS encryption, then set environment variable $env:PGSSLMODE="require" .
   2. 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).
   3. Do you want to change the database names away from the defaults of EdFi_Admin , EdFi_ODS, and EdFi_Security?
      
      
4. 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

Install databases on PostgreSQL and all three WebApps (Web API, Admin App, Swagger UI), and selecting the ODS populated template. (This is a good option for kicking the tires).

$parameters = @{ 
	engine = "postgresql"
	databaseServer = "myserver"
	databaseUser = "postgres" 
    useTemplates = $true 
	odsTemplate = "populated"
    webApiIisFolder = "c:\inetpub\ed-fi\webapi"
    swaggerIisFolder = "c:\inetpub\ed-fi\swagger"
    adminAppIisFolder = "c:\inetpub\ed-fi\adminapp"
}
 .\Initialize-Environment.ps1 @parameters

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

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

Examples

Install databases on PostgreSQL and all three WebApps (Web API, Admin App, Swagger UI), and selecting the ODS populated template. (This is a good option for kicking the tires).

$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 useTemplates = @{$true 
	engineodsTemplate = "postgresqlpopulated"
   	databaseServer webApiIisFolder = "myserver" 
	databaseUserc:\inetpub\ed-fi\webapi"
    swaggerIisFolder = "postgres" 
	dropDatabases = $true 
}c:\inetpub\ed-fi\swagger"
    adminAppIisFolder = "c:\inetpub\ed-fi\adminapp"
}
 .\Initialize-Environment.ps1 @parameters

Install Only install databases on SQL Server, with alternate port 1450, and deploy the Web APIPostgreSQL, using all available default values.

$parameters = @{ 
	engine = "sqlserverpostgresql"
	databaseServer = "myserver"
	databasePort = 1450
	useIntegratedSecurity = $true
	dropDatabases = $true
	webApiIisFolder"
	databaseUser = "c:\inetpub\ed-fi\webapipostgres" 
}
 .\Initialize-Environment.ps1 @parameters

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

$parameters = @{ 
	engine = "sqlserverpostgresql" 
	databaseServer = "myserver" 
	databasePortdatabaseUser = "postgres" 1450
	useIntegratedSecurityuseTemplates = $true
	dropDatabases = $true
	webApiIisFolderodsTemplate = "c:\inetpub\ed-fi\webapi"
	swaggerIisFolder = "c:\inetpub\ed-fi\swagger"
	admindatabase = "edfi_admin_rr"
	odsdatabase = "edfi_ods_rr"
	securitydatabase = "edfi_security_rr""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

3. Setup IIS Applications

As mentioned earlier,  configuration of IIS is up to the end user in the release candidate.  Some IIS configuration tips follow:

• 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 databasesManager, setup an Application for each, with custom app pools.
• Grant write access to the IIS_IUSRS account to the folder containing AdminApp assets, so that the secrets.json file can be updated during the Admin App's first-run configuration.

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 use the Admin App to generate client credentials (key and secret).
  • If you installed Admin App on server "myserver" with IIS Application named "AdminApp", then try loading https://myserver/AdminApp.

  • Click through the Admin App initial setup, and then before you do anything else, stop and restart the WebAPI web site via IIS Manager to force a security cache refresh.
    

    Tip
    If the initial setup screen reloads itself after the first time you click the setup button, then try waiting a few minutes for some background tasks to complete and then try again.

    
    

• Reload the Admin App and create a vendor and generate a key and secret.
• For more information on Admin App, please see:
  • User Guide
  • Securing the Admin App

• After creating a key and secret, you can use them in SwaggerUI or in the /wiki/spaces/ODSAPI33/pages/26443888.

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.