Contents:

Before You Install

This section provides general information you should review before installing the Ed-Fi ODS / API Admin API for v1.2.2.

Compatibility & Supported ODS / API Versions

This version of the Admin API has been tested and can be installed for use with the Ed-Fi ODS / API v3.4-v5.3 and 6.0-6.1.
See the Ed-Fi Technology Version Index for more details.

IMPORTANT INFORMATION FOR VERSION 1.2.2

Installation Instructions

Prerequisites

The following are required to install the Admin API with IIS:

• Enable IIS (before installing .NET Hosting Bundle).
• Install .NET 6 Hosting Bundle v6.0.6 or higher. After installing the .NET Hosting Bundle, it may be necessary to restart the computer for the changes to take effect.

Installation Steps

Step 1. Create Admin API Directory

Create a directory to hold all of the Admin API source files. In this example, we'll use a directory on the following path: "C:\Ed-Fi\AdminAPI".

Step 2. Rename and Unzip Admin API Source Files

Download and rename the linked Nuget Package (.npkg) to .zip

Unzip the contents into the folder created in Step 1.

There will be two folders. AdminApi folder will have binaries. Installer folder contains PowerShell scripts required for installation. 

Step 3. Ensure SQL Server Login Exists

In SQL Server Management Studio, make sure that you have a login for the database server. Guidance on how to set this up is explained in this blog post. A few basics:

• You can choose either Windows authentication or SQL Server authentication here.
• If you choose SQL Server authentication, make sure that if you have "User must change password at next login" checked. This means you must connect to SSMS with those credentials to reset the password. Otherwise, the app pools won't be able to connect.
• On the Server Roles page, ensure the "dbcreator" checkbox is checked since Entity Framework will create the database when the application is launched. You must do this when using either Windows or SQL Server authentication.

Once you have confirmed a proper SQL Server login exists, continue to the next step. 

Step 4. Configure App/Web Configuration Files

You will need to manually edit connection strings, authorization settings, and keys in "AdminApi\appsettings.json". Some values to note:

• Authentication Settings
  • Authentication:SigningKey  must be a Base64-encoded string
  • Authentication:Authority  and Authentication:IssuerUrl  should be the same URL as your application
  • Changing Authentication:AllowRegistration to true allows unrestricted registration of new Admin API clients
    • This is not recommended for production
• Change EnableSwagger  to true to enable generation of the Swagger UI documentation
  • This is not recommended for production.
• The connection strings will need to be accurately configured by the user. For more information on how to determine connection strings for your database, please reference Microsoft documentation.

Here is a snippet from a properly configured application settings file:

    "AppSettings": {
        "DatabaseEngine": "SqlServer",
        "DefaultOdsInstance": "EdFi ODS",
        "ProductionApiUrl": "https://YOUR_SERVER_NAME_HERE/WebApi/",
        "SecurityMetadataCacheTimeoutMinutes": "10",
        "ApiStartupType": "YOUR-MODE-HERE",
        "LocalEducationAgencyTypeValue": "Local Education Agency",
        "PostSecondaryInstitutionTypeValue": "Post Secondary Institution",
        "SchoolTypeValue": "School",
        "PathBase": "",
        "GoogleAnalyticsMeasurementId": "",
        "ProductRegistrationUrl": "https://edfi-tools-analytics.azurewebsites.net/data/v1/"
    },
    "Authentication": {
        "Authority": "https://YOUR_SERVER_NAME_HERE/AdminApi",
        "IssuerUrl": "https://YOUR_SERVER_NAME_HERE/AdminApi",
        "SigningKey": "YS1sb25nLXNhbXBsZQ==",
        "AllowRegistration": false
    },
    "EnableSwagger": false,
    "EnableDockerEnvironment": false,
    "ConnectionStrings": {
        "Admin": "Data Source=(local);Initial Catalog=EdFi_Admin;Trusted_Connection=True",
        "Security": "Data Source=(local);Initial Catalog=EdFi_Security;Trusted_Connection=True",
        "ProductionOds": "Data Source=(local);Initial Catalog=EdFi_Ods_Production;Trusted_Connection=True"
    },
    "Log4NetCore": {
        "Log4NetConfigFileName": "log4net\\log4net.config"
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Information"
        }
    },
    "AllowedHosts": "*"

Step 5. Create Self-Signed Certificate in IIS Manager

Open IIS Manager, and double-click on "Server Certificates". Note that we must select a server/machine in the left sidebar to see this option.

On the Server Certificate page, click on "Create Self-Signed Certificate..." on the Actions bar to the right.

For the certificate, use "Ed-Fi-ODS" as the friendly name and make sure the certificate store is set to "Personal". Click OK. We will use this certificate in an upcoming step.

Step 6. Create Necessary Application Pools

Back in the IIS Manager main page, expand the server/machine on the left sidebar and click on Application Pools.

Click on "Add Application Pool..." on the Actions bar to the right, enter "Ed-Fi" as the name. Click OK.

Once that is created, click on the "Ed-Fi" application pool and select "Advanced Settings..." on the Actions bar to the right. Change the Start Mode to "AlwaysRunning".

This next bit is optional if you want to use an app pool identity. If you would like to use the default "ApplicationPoolIdentity", then you can skip this section.

In the same Advanced Settings window, click on the browse icon under Process Model > Identity. Choose the custom account option and click "Set...". When setting the credentials, you can simply use the username and password that you use to log in to Windows. If you need to include the app pool domain in the username, then the username can look something like this: "localhost\username", where "localhost" is the app pool domain. Once you've entered the correct credentials, click OK on all screens until you're back to the main Application Pools page.

After that's done, we'll repeat the exact same steps in this section, but enter "Admin API" as the Application Pool name. We should now have 2 app pools.

Step 8. Create Admin API Website

On the left sidebar, we'll right-click on the newly created "Ed-Fi" website, select "Add Application...", and perform the following:

1. Enter "Admin API" for the Alias.
2. For the Application pool, select the Admin API app pool.
3. The Physical path should be set to the path of the Admin API folder (located in directory with Admin API source files).
4. Hit OK.

Step 9. Execute First-Time Configuration

Continue on to 1.2First-Time Configuration for Admin API.