This section describes how to set up the Ed-Fi ODS / API v7.0 in single/multi tenant mode. Before you proceed, make sure you have installed the prerequisites listed in Getting Started - Binary Installation.

Table of Contents

maxLevel	1
exclude	Contents

Step 1. Download the Ed-Fi ODS / API Installer Packages

The Ed-Fi ODS / API installation packages can be downloaded from the following links:

Package Links

The required release packages to install the Ed-Fi ODS / API can be found at the links below. We recommend you stay current with the latest patch update that has been promoted to release.

EdFi.Suite3.Installer.WebApi
EdFi.Suite3.Installer.SwaggerUI (Optional, not for production)
EdFi.Suite3.RestApi.Databases.5.0.0

For each of the downloads, right-click and select "Properties." Update the file extension (from .nupkg to .zip). Remove the version number (optional). Check the box next to Unblock (this will prevent PowerShell from asking for permission to load every module in the installer) and click OK.

Info
You may need to configure TLS while running the installation scripts described in steps below. `[Net.ServicePointManager]::SecurityProtocol += [Net.SecurityProtocolType]::Tls12`

Step 2. Install the Ed-Fi Databases

Extract the contents of the EdFi.Suite3.RestApi.Databases package. The paths in these instructions assume that the package was extracted to a folder with the name of the package (e.g., C:\temp\EdFi.Suite3.RestApi.Databases).

Edit the configuration.json File

There are several settings in the configuration file that are left empty as they depend on whether you are opting of SQL Server or PostgreSQL backend. Update the settings by consulting the samples provided below.

Deck

history	false
id	dbconfig

Card

label	SQL Server

Code Block

language	xml

 "ConnectionStrings": {
     "EdFi_Ods": "server=(local);trusted_connection=True;database=EdFi_{0};Application Name=EdFi.Ods.WebApi",
     "EdFi_Security": "server=(local);trusted_connection=True;database=EdFi_Security;persist security info=True;Application Name=EdFi.Ods.WebApi",
     "EdFi_Admin": "server=(local);trusted_connection=True;database=EdFi_Admin;Application Name=EdFi.Ods.WebApi",
     "EdFi_Master": "server=(local);trusted_connection=True;database=master;Application Name=EdFi.Ods.WebApi"
  },
  "InstallType": "SingleTenant",
  "ApiSettings": {
   "Engine": "SQLServer",
   ...
   "MinimalTemplateScript": "TPDMCoreMinimalTemplate",
   "PopulatedTemplateScript": "TPDMCorePopulatedTemplate"
  }

Card

label	PostgreSQL

Code Block

language	xml

 "ConnectionStrings": {
     "EdFi_Ods": "host=localhost;port=5432;username=postgres;database=EdFi_{0};Application Name=EdFi.Ods.WebApi",
     "EdFi_Security": "host=localhost;port=5432;username=postgres;database=EdFi_Security;Application Name=EdFi.Ods.WebApi",
     "EdFi_Admin": "host=localhost;port=5432;username=postgres;database=EdFi_Admin;Application Name=EdFi.Ods.WebApi",
     "EdFi_Master": "host=localhost;port=5432;username=postgres;database=postgres;Application Name=EdFi.Ods.WebApi"
  },
  "InstallType": "SingleTenant",
  "ApiSettings": {
   "Engine": "PostgreSQL",
   ...
   "MinimalTemplateScript": "TPDMCorePostgreSqlMinimalTemplate",
   "PopulatedTemplateScript": "TPDMCorePostgreSqlPopulatedTemplate"
  }

Card

label	SQL Server (MultiTenant)

Code Block

language	xml

"InstallType": "MultiTenant",  
"ApiSettings": { 
   "Engine": "SQLServer",
   "OdsTokens": "Tenant1ODS;Tenant2ODS"
   "Features": [
     ...
     {
        "IsEnabled": true,
        "Name": "MultiTenancy"
     },
     ...
   ]
},
"Tenants" : {
  "Tenant1": {
      "ConnectionStrings": {
        "EdFi_Security":  "server=(local);trusted_connection=True;database=EdFi_Security_Tenant1;persist security info=True;application name=EdFi.Ods.WebApi;encrypt=False",
        "EdFi_Admin":  "server=(local);trusted_connection=True;database=EdFi_Admin_Tenant1;application name=EdFi.Ods.WebApi;encrypt=False"
      }
    },
  "Tenant2": {
      "ConnectionStrings": {
        "EdFi_Security":  "server=(local);trusted_connection=True;database=EdFi_Security_Tenant2;persist security info=True;application name=EdFi.Ods.WebApi;encrypt=False",
        "EdFi_Admin":  "server=(local);trusted_connection=True;database=EdFi_Admin_Tenant2;application name=EdFi.Ods.WebApi;encrypt=False"
      }
    }
}

Card

label	PostgreSQL (MultiTenant)

Code Block

language	xml

"InstallType": "MultiTenant",  
"ApiSettings": { 
   "Engine": "PostgreSQL",
   "OdsTokens": "Tenant1ODS;Tenant2ODS"
   "Features": [
     ...
     {
        "IsEnabled": true,
        "Name": "MultiTenancy"
     },
     ...
   ]
},
"Tenants" : {
  "Tenant1": {
      "ConnectionStrings": {
        "EdFi_Security":  "host=localhost;port=5432;username=postgres;database=EdFi_Security_Tenant1;application name=EdFi.Ods.WebApi",
        "EdFi_Admin":  "host=localhost;port=5432;username=postgres;database=EdFi_Admin_Tenant1;application name=EdFi.Ods.WebApi"
      }
    },
  "Tenant2": {
      "ConnectionStrings": {
        "EdFi_Security":  "host=localhost;port=5432;username=postgres;database=EdFi_Security_Tenant2;application name=EdFi.Ods.WebApi",
        "EdFi_Admin":  "host=localhost;port=5432;username=postgres;database=EdFi_Admin_Tenant2;application name=EdFi.Ods.WebApi"
      }
    }
}

Info
Use OdsTokens to deploy year specific ODS databases

Expand

title	Optional: Click here to see custom extension Plugin deployment steps...

Copy your extension plugin to database deployment package

If you have an extension plugin package that you would like to be the deployed to Ed-Fi Databases, place the extracted contents of your extension plugin package in the extracted EdFi.Suite3.RestApi.Databases package under Ed-Fi-ODS-Implementation\Plugin folder.

Enable your extension plugin in the deployment configuration

Edit the Plugin section of the configuration file and update the Folder and Scripts values to the following:

Code Block
"Plugin": { "Folder": "../../Plugin", "Scripts": [ ] }

Run Installation Script

Open a PowerShell window in Administrator mode and navigate to the EdFi.Suite3.RestApi.Databases package folder.

Run the following PowerShell command to load modules for installation:

Code Block
Import-Module .\Deployment.psm1

Next, execute the following command in PowerShell:

Code Block
Initialize-DeploymentEnvironment

Step 3. Install WebApi

Extract the contents of the EdFi.Suite3.Installer.WebApi package. The paths in these instructions assume that the package was extracted to a folder with the name of the package (e.g., C:\temp\EdFi.Suite3.Installer.WebApi).

Prepare Installation script

Open a PowerShell window in Administrator mode and navigate to the EdFi.Suite3.Installer.WebApi package folder. Run the following PowerShell command to load modules for installation:

Code Block
Import-Module .\Install-EdFiOdsWebApi.psm1

The WebApi installer can take a number of parameters to tailor the installation experience (more examples can be found in the Install-EdFiOdsWebApi.psm1 file). At a minimum, database connection info is required.

Copy and modify the following parameter code to fit your connection information:

Deck

history	false
id	apiInstall

Card

label	SQL Server

Code Block

language	powershell

$parameters = @{
    PackageVersion = "7.0.2250"
    PackageName = "EdFi.Suite3.Ods.WebApi.Standard.5.0.0"
    DbConnectionInfo = @{
       Engine="SqlServer"
       Server="localhost"
       UseIntegratedSecurity=$true
    }
    UnEncryptedConnection = $true
}

Card

label	PostgreSQL

Code Block

language	powershell

$parameters = @{
    PackageVersion = "7.0.2250"
    PackageName = "EdFi.Suite3.Ods.WebApi.Standard.5.0.0"
    DbConnectionInfo = @{ 
       Engine="PostgreSQL" 
       Server="localhost" 
       Username="postgres"
    }
}

Card

label	SQL Server (MultiTenant)

Code Block

language	powershell

$parameters = @{
    IsMultiTenant = $true
    PackageVersion = "7.0.2250"
    PackageName = "EdFi.Suite3.Ods.WebApi.Standard.5.0.0"
    DbConnectionInfo = @{
       Engine="SqlServer"
       Server="localhost"
       UseIntegratedSecurity=$true
    }
    UnEncryptedConnection = $true
    Tenants = @{
    	Tenant1 = @{
        	AdminDatabaseName = "EdFi_Admin_Tenant1"
            SecurityDatabaseName = "EdFi_Security_Tenant1"
        }
        Tenant2 = @{
            AdminDatabaseName = "EdFi_Admin_Tenant2"
            SecurityDatabaseName = "EdFi_Security_Tenant2"
        }
    } 
}

Card

label	PostgreSQL (MultiTenant)

Code Block

language	powershell

$parameters = @{
    IsMultiTenant = $true
    PackageVersion = "7.0.2250"
    PackageName = "EdFi.Suite3.Ods.WebApi.Standard.5.0.0"
    DbConnectionInfo = @{ 
       Engine="PostgreSQL" 
       Server="localhost" 
       Username="postgres"
    }
    Tenants = @{
    	Tenant1 = @{
        	AdminDatabaseName = "EdFi_Admin_Tenant1"
            SecurityDatabaseName = "EdFi_Security_Tenant1"
        }
        Tenant2 = @{
            AdminDatabaseName = "EdFi_Admin_Tenant2"
            SecurityDatabaseName = "EdFi_Security_Tenant2"
        }
    }   
}

Info

title	Use of UnEncryptedConnection parameter

UnEncryptedConnection = $true will add Encrypt=false to the connection strings to mitigate a breaking change in the Microsoft.Data.SqlClient library. This setting is not recommended for production environments; for production environments, is recommended to follow the steps to Install a valid certificate on the server.

Info

title	ODS Connection String Encryption

By default, an Encryption key will be generated using member New-AESKey from Install-EdFiOdsWebApi.psm1 module. If you need to override the value with an specific key, add OdsConnectionStringEncryptionKey parameter. Key must be 256 bits and base 64 encoded.

Info

To enable Context-Based Routing for Year-Specific ODS, set a valid value for OdsContextRouteTemplate parameter.

An example of a valid value is “{schoolYear:range(2020,2030)}”
Where schoolYear is the Route section, and the range will accept values between 2020 and 2030

Paste the modified parameter code into your PowerShell window and hit Enter.

Run the Installation Script

Run the following command in the PowerShell window:

Code Block
Install-EdFiOdsWebApi @parameters

Expand

title	Optional: Click here to see custom extension Plugin deployment steps...

Copy your extension plugin to deployed WebAPI

If you have an extension plugin package that you would like to be the deployed to Ed-Fi WebApi, place the extracted contents of your extension plugin package in C:\inetpub\Ed-Fi\WebApi\Plugin folder.

Enable your extension plugin in appsettings.json

Open the appsettings.json file found in C:\inetpub\Ed-Fi\WebApi.

Edit the Plugin section of the configuration file and update the Folder and Scripts values to the following:

Code Block
"Plugin": { "Folder": "./Plugin", "Scripts": [ ] }

Step 4. Install Swagger

Extract the contents of the "EdFi.Suite3.Installer.SwaggerUI" package. The paths in these instructions assume that the package was extracted to a folder with the name of the package (e.g., C:\temp\EdFi.Suite3.Installer.SwaggerUI).

Prepare Installation Script

Open a PowerShell window in Administrator mode and navigate to the "EdFi.Suite3.Installer.SwaggerUI" folder. Run the following PowerShell command to load modules for installation:

Code Block
Import-Module .\Install-EdFiOdsSwaggerUI.psm1

The Swagger UI installer can take a number of parameters to tailor the install experience (more examples can be found in the Install-EdFiOdsWebApi.psm1 file). At a minimum, WebAPI connection information is required.

Copy and modify the following parameter code to add your site name:

Code Block
$parameters = @{ PackageVersion = "7.0.2249" WebApiVersionUrl = "https://YOUR_SITE_OR_SERVER_NAME_HERE/WebApi" }

Paste the modified parameter into your PowerShell window and execute the code.

Info

To deploy Swagger for MultiTenant, use parameters Tenants and DefaultTenant (Optional. Used to specify one tenant to be displayed as default).

Code Block

language	xml

$parameters = @{
    PackageVersion = "7.0.2249"
    WebApiVersionUrl = "https://YOUR_SITE_OR_SERVER_NAME_HERE/WebApi"
	Tenants = @("Tenant1", "Tenant2")
	DefaultTenant = "Tenant2"
}

If deploying multiple school years, use parameters SchoolYears and DefaultSchoolYear (Optional. Used to specify one school year to be displayed as default)

Code Block

language	xml

$parameters = @{
    PackageVersion = "7.0.2249"
    WebApiVersionUrl = "https://YOUR_SITE_OR_SERVER_NAME_HERE/WebApi"
    SchoolYears = @("2022", "2023")
    DefaultSchoolYear = "2023"
}

Run the Installation Script

Run the following command in the PowerShell window:

Code Block
Install-EdFiOdsSwaggerUI @parameters

Step 5. Install Admin API

The Admin API provides an API-based programmatic interface for platform hosts to administer and manage non-sandbox instances of the Ed-Fi ODS / API. Follow the installation steps here. Alternatively, Alternatively, ODS instances can be configured by database administrators via SQL queries as outlined in the article How To: Configure ODS Instances. API keys and secrets can be administered by database administrators via SQL queries as outlined in the article article How To: Configure Key / Secret.

Step 6. Restart your Website

Just a few more tasks to complete your installation:

Open IIS (Press the Windows key on your keyboard, type IIS, select Internet Information Services (IIS), and press Enter.
Right-click on the server (alternatively, you can right-click the EdFi web site), and select Stop.

Right-click the server (or EdFi website) again and select Start.

You are now ready to use the Ed-Fi ODS / API. The following URLs are available:

Website	URL
Ed-Fi ODS / API	https://YOUR_SERVER_NAME_HERE/WebApi/
Ed-Fi Admin AppApi	https://YOUR_SERVER_NAME_HERE/AdminAppAdminApi/
Ed-Fi ODS / API Documentation (Optional, not for production)	https://YOUR_SERVER_NAME_HERE/SwaggerUI

Include Page

	_Sidebar - Getting Started
	_Sidebar - Getting Started

Versions Compared

Old Version 21

New Version Current

Key

Step 1. Download the Ed-Fi ODS / API Installer Packages

Package Links

Step 2. Install the Ed-Fi Databases

Edit the configuration.json File

Run Installation Script

Step 3. Install WebApi

Prepare Installation script

Run the Installation Script

Step 4. Install Swagger

Prepare Installation Script

Run the Installation Script

Step 5. Install Admin API

Step 6. Restart your Website

Page Comparison

Versions Compared

Old Version 21

New Version Current

Key

Step 1. Download the Ed-Fi ODS / API Installer Packages

Package Links

Step 2. Install the Ed-Fi Databases

Edit the configuration.json File

Run Installation Script

Step 3. Install WebApi

Prepare Installation script

Run the Installation Script

Step 4. Install Swagger

Prepare Installation Script

Run the Installation Script

Step 5. Install Admin API

Step 6. Restart your Website