Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: update to 6.2

Contents:

Table of Contents
maxLevel2

Panel
borderColor#fec43d
bgColor#ffedc4
titleColor#000
borderWidth1
titleBGColor#fec43d
borderStylesolid
titleAdmin API Installation for Docker or On-Premises IIS
The following is the DockerHub repo for Admin API v1.2.2 Docker Image for inclusion in Docker compose:

edfialliance/ods-admin-api:v1.

2

.2

  • edfialliance/ods-admin-api-db:v1.2.2

  • Before You Install

    This section provides general information you should review before installing the Ed-Fi ODS / API Admin API for v1.24.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.3and 6.0-62. 1. See the Ed-Fi Technology Version Index for more details.

    IMPORTANT INFORMATION FOR VERSION 1.2.2

    Warning
    titleODS API dependency
    Admin API v1.2.2 depends on ODS API for identifying the security model version

    .

    So, please make sure to have an instance of the Ed-Fi ODS / API v3.4-v5.3 or v6.0-v6.1 deployed and operational before you can use the Admin API. 

    Warning
    titleManual First-Time Setup

    Admin API v1.2.2 requires minor extra setup after the instructions outlined below. These may be automated in future releases and could require additional steps to support upgrading. See Copy - First-Time Configuration for Admin API for more details.

    Warning
    titleLoad Balancing and Horizontal Scaling Not Supported

    Admin API v1.2.2 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.

    Info
    titleUpgrading

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

    Installation Instructions

    General Prerequisites

    The following are required to install the Admin API:

    • The Admin API provides an interface to administer an Ed-Fi ODS / API. Understandably, you must have an instance of the Ed-Fi ODS / API v3.4 - v5.3 or 6.0-6.1 2 deployed and operational before you can use the Admin API. Tested configurations include on-premises installation via binary installation or source code installation
    • A SQL Server 2012 or higher, or Postgres 11 or higher database server (i.e., the same platform requirement applicable to your ODS / API v3.4 through v5.3.0 installation).
    • A modern web browser such as Google Chrome, Mozilla Firefox, or Microsoft Edge is required to view live Swagger documentation. Internet Explorer 11 (a pre-installed browser on Windows Server) may load but may not function when using Admin API.

    Installation Instructions

    Admin API is not included with the ODS-Docker solution by default, but can be hosted as part of that ecosystem.

    To install Admin API on Docker, first Install the ODS / API Docker environment following these instructions. Then, apply the below changes to the environment to introduce the Admin API.  Admin API does not support in-place upgrades from prior versions.  Please install a fresh copy of Admin API to upgrade from prior versions.

    1. Include Admin API in the ODS Docker Setup

    Docker Compose

    Add the following to your docker-compose.yml  file. This can be done either instead of or in addition to the adminapp  service.

    Admin API Application

    This service depends on the pb-admin  and subsequently db-admin services to run.

    Code Block
    languageyml
    titledocker-compose.yml
    # ... above are other services
    adminapi:
        build:
        image: edfialliance/ods-admin-api:${ADMIN_API_TAG}
        environment:
          ADMIN_POSTGRES_HOST: pb-admin
          POSTGRES_PORT: "${PGBOUNCER_LISTEN_PORT:-6432}"
          POSTGRES_USER: "${POSTGRES_USER}"
          POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
          DATABASEENGINE: "PostgreSql"
          API_MODE: ${API_MODE}
          AUTHORITY: ${AUTHORITY}
          ISSUER_URL: ${ISSUER_URL}
          SIGNING_KEY: ${SIGNING_KEY}
          ADMIN_API_VIRTUAL_NAME: ${ADMIN_API_VIRTUAL_NAME:-adminapi} 
          API_INTERNAL_URL: ${API_INTERNAL_URL}
        volumes:
          - ../../Docker/ssl:/ssl/
        depends_on:
          - pb-admin
        restart: always
        hostname: ${ADMIN_API_VIRTUAL_NAME:-adminapi} 
        container_name: adminapi
        healthcheck:
          test: $$ADMIN_API_HEALTHCHECK_TEST
          start_period: "60s"
          retries: 3
    # ... below are network and volume configs

    Admin API Database

    For the most part, the Admin API shares the same database schema as the Admin App. However, there are a few tables required for storing API client authentication which need to be initialized manually. You can see the details in Copy - First-Time Configuration for Admin API1.x.

    Rather than introducing these tables explicitly, for Docker we have provided an alternative image for use with Admin API: edfialliance/ods-admin-api-db, which is to be used in place of the existing edfialliance/ods-api-db-admin image for your DB service.

    If you are introducing Admin API to an existing composition do NOT change the volume mapping configuration in order to preserve your data. Only change the image and tag of the existing service. The below block is a sample of this, based on an example ODS / API Docker environment composition. Make sure you update the mode ("SharedInstance", "YearSpecific", or "DistrictSpecific") accordingly.

    Code Block
    languageyml
    titledocker-compose.yml
    # ... above are other services
    db-admin:
        image: edfialliance/ods-admin-api-db-admin:${ADMIN_API_DB_TAG}
        environment:
          POSTGRES_USER: "${POSTGRES_USER}"
          POSTGRES_PASSWORD: "${POSTGRES_PASSWORD}"
          API_MODE: <YOUR MODE HERE>
        volumes:
          - vol-db-admin:/var/lib/postgresql/data
        restart: always
        container_name: ed-fi-db-admin
    # ... below are other services

    .env Settings

    Add the following to your environment settings file to support Admin API. Note that when running both Admin App and Admin API, some of these settings may overlap. This is expected, and the same values can be used.

    Code Block
    languagetext
    title.env for Admin API
    ADMIN_API_TAG=<version of image to run>
    ADMIN_API_DB_TAG=<version of image to run> 
    API_MODE=<API Mode Eg. SharedInstance, YearSpecific, DistrictSpecific>
    ADMIN_API_VIRTUAL_NAME=<virtual name for the Admin API endpoint>
    ODS_VIRTUAL_NAME=<virtual name for the ods endpoint>
    
    # For Authentication
    AUTHORITY=<Authentication Authority Appsetting Eg. http://localhost/${ADMIN_API_VIRTUAL_NAME}>
    ISSUER_URL=<Authentication IssuerUrl Appsetting Eg. https://localhost/${ADMIN_API_VIRTUAL_NAME}>
    SIGNING_KEY=<Authentication Signing Key (Symmetric Security Key) for Auth Tokens>
    
    # For Postgres only
    POSTGRES_USER=<default postgres database user>
    POSTGRES_PASSWORD=<password for default postgres user>
    PGBOUNCER_LISTEN_PORT=<port for pg bouncer to listen to>
    
    # The following needs to be set to specify a health check test for Admin api.
    # RECOMMENDED: To use the default internal Admin Api health check endpoint, set the variable as follows:
    ADMIN_API_HEALTHCHECK_TEST="curl -f http://${ADMIN_API_VIRTUAL_NAME}/health"
    #  To disable the health check, remove the above and instead set the variable as follows:
    # ADMIN_API_HEALTHCHECK_TEST=/bin/true
    #  To add a custom health check, consult the documentation at https://docs.docker.com/compose/compose-file/compose-file-v3/#healthcheck
    
    # The following needs to be set to specify the ODS API endpoint for Admin API to internally connect.
    # If user chooses direct connection between ODS API and Admin API within docker network, then set the api internal url as follows
    API_INTERNAL_URL = http://${ODS_VIRTUAL_NAME}

    Nginx / Gateway Configuration

    Update your nginx server configuration to include the Admin API in the reverse proxy.

    Code Block
    titledefault.conf.template
    # upstream server config...
    
    server {
        #listen / server config...
        #ssl_certificate config...
    
        # other locations...
    
        location /${ADMIN_API_VIRTUAL_NAME} {
            client_max_body_size 20M;
            proxy_pass http://${ADMIN_API_VIRTUAL_NAME};
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Port 443;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        }
    }

    2. Relaunch the Docker Composition

    After updating the files, restart the docker composition.

    Code Block
    languagebash
    docker compose -f ./compose/your-compose-file.yml --env-file ./.env up -d

    3. Execute First-Time Configuration

    Continue on to Copy - First-Time Configuration for Admin 1.x.


    Panel
    borderColor#fec43d
    bgColor#ffedc4
    titleColor#000
    borderWidth1
    titleBGColor#fec43d
    borderStylesolid
    titleAdmin API Installation for Docker or On-Premises IIS

    The following is the DockerHub repo for Admin API v1.4.2 Docker Image for inclusion in Docker compose: