Contents:

Before You Install

This section provides general information to review before installing the Ed-Fi ODS / API Admin API for v2.0.1.

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 v7.0. See the Ed-Fi Technology Version Index for more details.

Installation Instructions

Prerequisites

A running instance of the ODS / API v7.0 platform must be configured and running before installing Admin API.  

Admin API only supports running one instance of the application at a time in an ODS / API ecosystem. Future versions may allow for scaling and load balancing.

Admin API does not support in-place upgrades from prior versions.  Please install a fresh copy of Admin API to upgrade from prior versions.

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

Each step is outlined in detail below for the PowerShell deployment. Ensure that you have permission to execute PowerShell scripts. For more information, see http://go.microsoft.com/fwlink/?LinkID=135170.

Step 1. Rename and Unzip Admin API Source Files

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

Unzip the contents.

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

Step 2. Configure Installation

Open the "install.ps1" file in a text editor. You will need to edit this file with your configuration details. If a value is not present for any of the parameters, it will use its default value.

Note: Editing Items 3(a, b) and 4b below are mandatory for installation to complete.

1. Configure $dbConnectionInfo. These values are used to construct the connection strings.

   1. Server. The name of the database server. For a local server, we can use "(local)" for SQL and "localhost" for PostgreSQL.

   2. Engine. Admin App supports SQL and PostgreSQL database engines. So setting up the Engine will decide which database engine to be used. Valid values are "SQLServer" and "PostgreSQL".
   3. UseIntegratedSecurity. Will either be "$true" or "$false".
      1. If you plan to use Windows authentication, this value will be "$true"
      2. If you plan to use SQL Server/ PostgreSQL server authentication, this value will be "$false" and the Username and Password must be provided.
   4. Username. Optional. The username to connect to the database. If UseIntegratedSecurity is set to $true, this entry is not needed
   5. Password. Optional. The password to connect to the database. If UseIntegratedSecurity is set to $true, this entry is not needed
   6. Port. Optional. Used to specify the database server port, presuming the server is configured to use the specific port.
2. Configure $adminAppFeatures. These values are used to set Optional overrides for features and settings in the appsetting.json.
   1. ApiMode. Possible values: sharedinstance, districtspecific and yearspecific. Defaults to sharedinstance

3. Configure $authenticationSettings. These values are mandatory for authentication process.

               a. SigningKey: must be a Base64-encoded string
               b. Authority and IssuerUrl: should be the same URL as your application
               c. AllowRegistration: to true allows unrestricted registration of new Admin API clients. This is not recommended for production. 

     4. Configure $p. This is the variable used to send all the information to the installation process.

1. 1. ToolsPath. Path for storing installation tools, e.g., nuget.exe. Defaults to "C:/temp/tools"
   2. OdsApiUrl. Base URL for the ODS / API. Mandatory.
   3. PackageVersion. Optional. If not set, will retrieve the latest full release package.

$dbConnectionInfo = @{
        Server = "(local)"
        Engine = "SqlServer"
        UseIntegratedSecurity = $false
        Username = "exampleAdmin"
        Password = "examplePassword"
}
$adminApiFeatures = @{
    ApiMode = "sharedinstance"
}
$authenticationSettings = @{
    Authority = "https://localhost/adminapi"
    IssuerUrl = ""https://localhost/adminapi"
    SigningKey = "Base64-encoded string"
    AllowRegistration = $false
}
$p = @{
    ToolsPath = "C:/temp/tools"
    DbConnectionInfo = $dbConnectionInfo
    OdsApiUrl = "http://web-api.example.com/WebApi"
    PackageVersion = '2.0.1.0'
    PackageSource = $adminApiSource
    AuthenticationSettings = $authenticationSettings
    AdminApiFeatures = $adminApiFeatures
}

$dbConnectionInfo = @{
        Server = "localhost"
        Engine = "PostgreSQL"
        UseIntegratedSecurity = $false
        Username = "postgres"
        Password = "examplePassword"
}
$adminApiFeatures = @{
    ApiMode = "sharedinstance"
}
$authenticationSettings = @{
    Authority = "https://localhost/adminapi"
    IssuerUrl = ""https://localhost/adminapi"
    SigningKey = "Base64-encoded string"
    AllowRegistration = $false
}
$p = @{
    ToolsPath = "C:/temp/tools"
    DbConnectionInfo = $dbConnectionInfo
    OdsApiUrl = "http://web-api.example.com/WebApi"
    PackageVersion = '2.0.1.0'
    PackageSource = $adminApiSource
    AuthenticationSettings = $authenticationSettings
    AdminApiFeatures = $adminApiFeatures
}

Step 3. Open a PowerShell Prompt in Administrator Mode 

Method 1: Open [Windows Key]-R which will open a Run dialog for tasks needing administrative privileges. Type "PowerShell" to open a PowerShell prompt in Administrator mode.

Method 2: Click on the Windows icon in the lower-left corner. Type "PowerShell" and right-click the "Windows PowerShell" option when provided. Select "Run as Administrator" to open a PowerShell prompt in Administrator mode.

Change the directory to the unzipped directory for the Admin Api Installer.

Step 4 . Run the Installation via PowerShell

Run "install.ps1" script.

Database login setup on integrated security mode:

During the installation process, you will be prompted to choose database login details. Entering "Y" will continue with default option (Installation process will create IIS APPPOOL\AdminApi database login on the server).

Choosing 'n' will prompt you to enter windows username. The installation process will validate and create database login using entered username, if the login does not exist on the database server already. 

Installation completed:

Installation process will install Admin Api application and create required database tables.

Step 5. Verify SQL Server Login

The installation process sets up an appropriate SQL Login for use with the dedicated AdminApi Application Pool in IIS. You can verify this in SQL Server Management Studio:

On the Server Roles page, make sure that  "public" and "sysadmin" checkboxes are checked. Once you have confirmed a proper SQL Server login exists, continue to the next step. 

Step 6. Update Application Pool Identity (Optional)

As mentioned on Step 5, installation process sets up an appropriate SQL Login for use with the dedicated AdminApi Application Pool in IIS. If you would like to use the default "ApplicationPoolIdentity", then you can skip this bit.

Else in the Advanced Settings window, click on the browse icon under Process Model > Identity. We'll choose the custom account option and click "Set...". When setting the credentials, you can just 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 we have entered the correct credentials, we'll click OK on all screens until we're back to the main Application Pools page.

Step 7. Confirming appSettings.json

Change EnableSwagger  to true to enable generation of the Swagger UI documentation.

• • This is not recommended for production.

Step 9. Execute First-Time Configuration

Continue on to First-Time Configuration for Admin API 2.x.