Getting Started - Binary Installation

Owned by Ian Christopher (Deactivated)
Last updated: Oct 18, 2023 by Stephen FuquaVersion comment

This section describes how to set up the Ed-Fi ODS / API v6.1 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

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