Getting Started - Binary Installation

Owned by Vinaya Mayya
Last updated: Oct 18, 2023 by Stephen Fuqua
6 min read

This section describes how to set up the Ed-Fi ODS / API v7.0Ā using the release binaries listed inĀ Binary Releases. This is a recommend approach for implementations that have no requirement to extend or customize the source code of the Ed-Fi ODS /Ā API.

Before binary installation, install the prerequisites listed in the following steps:Ā 

Detail on each step follows.

Step 1. Install and Configure Windows Components

Database Server

Ensure that the following components are installed:

  • PowerShell 5.0-7.2.Ā PowerShell is used by the database deployment scripts.
    (warning) PowerShell 7.3 has a known problem, please be sure to use 7.2 or lower. See ODS-5656 - Getting issue details... STATUS

  • .NET 6.0 SDK. Required by theĀ Database Deploy Tool used in theĀ database deployment scripts.

    Ā View detail...

    PowerShell 5.0

    Verify that PowerShell 5.0 or above is installed:

    1. Press theĀ Windows keyĀ Windows logoĀ on your keyboard, typeĀ PowerShell, selectĀ Windows PowerShell, and pressĀ Enter.

    2. TypeĀ $PSVersionTable.PSVersion, and pressĀ Enter.Ā 

    3. If the required version is not installed, downloadĀ Windows Management Framework 5.0,Ā which includes PowerShell 5.0.


    .NET 6.0 SDK

    Download and install the latest release of theĀ .NET 6.0 SDK

Web ServerĀ 

Ensure that the following components are installed:

  • Internet Information Services.Ā IIS is the web server that will run the ODS / API.

  • .NET 6.0 Hosting Bundle. The .NET 6.0 Hosting Bundle is required for running the API on IIS. Must be installed after IIS.

    Ā View detail...

    Internet Information Services

    1. Press theĀ Windows keyĀ Windows logoĀ on your keyboard, type "features", selectĀ Turn Windows features on or off, pressĀ Enter.

    2. Check the box next to Internet Information Services. The default selections will be good for most cases.

    3. Click OK.


    .NET 6.0 Hosting Bundle

    Download and installĀ .NET Hosting Bundle 6.0.

Step 2. Install and Configure Required Software

Ensure that the following software is installed and configured on the database server:

  • Microsoft SQL Server 2019. Microsoft SQL Server is used to store the data for the Ed-Fi ODS / API. Standard, Developer, or Enterprise Editions are supported.Ā 
  • Alternative PostgreSQL datastore:Ā PostgreSQL 13.x. can be used as the datastore for Ed-Fi ODS / API instance instead of Microsoft SQL Server.
Ā View detail...

PostgreSQL Installation (Optional)

Install PostgreSQL 13.x on port 5432 if you intend to use PostgreSQL as a backing datastore for the ODS / API.

PostgreSQL Visualization Tool

Unlike SQL Server, PostgreSQL does not include a GUI to visualize the database (commands are executed via the command line using psql). Below is a list of various tools that work:

Install PostgreSQL

Installation of PostgreSQL can be done either using the binaries or using Docker. The recommended solution is to use the docker install using Linux containers.

Option 1. Installation using PostgreSQL Installer

Ā InstallationĀ using PostgreSQL Installer
  • Install using the PostgreSQLĀ installer. Version 13.x is compatible with the ODS / API.

Download the version 13.x installer.

Click Next.

Click Next.

If you want to install only the tools uncheck PostgreSQL Server, pgAdmin 4 and Stack Builder.

Click Next.


Click Next.

Enter a password for the Postgres superuser.

Click Next.

Enter port 5432 (default).

Click Next.

Click Next.

Click Next.

Click Next to finish the installation.

Option 2. PostgreSQL InstallationĀ with Docker

Ā Installation with Docker

Initial setup with Docker:

  • Install Docker using thisĀ guide.
  • Create a Docker Compose file.

Run PostgreSQL with Docker in Linux Containers

Create a Docker Compose file (name:Ā docker-compose.yml)Ā to bootstrap PostgreSQL using Linux containers. More information on the Docker Compose file can be found on the Docker documentation site.Ā 

version: '3.7'
services:
    pg13:
        image: postgres:13-alpine
        container_name: pg13
        volumes:
            - pg13-database:/var/lib/postgresql/data
        ports:
            - 5432:5432
        environment:
            - POSTGRES_PASSWORD=${PG_PASSWORD}
        restart: on-failure
volumes:
    pg13-database:
        driver: local
        name: pg13-database

Create an environment file (name: .env) to be consumed by Docker Compose. By default the environment file needs to be in the same folder as the Docker Compose file.

PG_PASSWORD=P@ssw0rd

Sample files for these can be downloaded from the download panel on the right.

Data Retention and Docker Compose

Once you have set up your docker-compose.yml and .env files and placed them in a folder (e.g.,Ā C:\PGDockerSetup), navigate to that folder in PowerShell and run docker-compose. This utility reads theĀ docker-compose.yml configuration file and runs all of the containers described in that file.Ā 

To bring up the environment:Ā 

C:\PGDockerSetup>docker-compose up -d

To stop the volumes and containers:

C:\PGDockerSetup>docker-compose down

To stop the services and remove them, but retain the data in separate volumes:

C:\PGDockerSetup>docker-compose down -v

Configure pgpass.conf

A pgpass.conf file must be set up to store passwords in a location accessible by IIS. It is required by database deployment scripts for the ODS / API. Additionally, a PGPASSFILE environment variable should be setup to specify the location of pgpass.conf file.

Create a pgpass.conf file. Note that the password should be your Postgres superuser password and if you are deploying Postgres via Docker, it should match the password in your environment file.

localhost:5432:*:postgres:P@ssw0rd

Set the environment variable PGPASSFILE to the location of the pgpass file that was created, which is the recommended approach.Ā Optionally, the file can be saved in %APPDATA%/postgresql/pgpass.conf.

You can test theĀ environment variable setup using:Ā Ā 

C:\> get-item env:pgpassfile

Name                           Value
----                           -----
PGPASSFILE                     C:\PGDockerSetup\pgpass.conf


Step 3. Install and Configure ODS / APIĀ 

PowerShell installers released with the ODS / API provide varied configuration options. The primary ODS / API install use cases are provided as examples below. Choose the option that suits your need and customize parameters as needed.

Contents

Find out more about how to begin using the Ed-Fi ODS / API:

Downloads

The following link contains sample docker setup files for PostgreSQL

PGDockerSetup.zip