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.
Warning |
---|
|
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 |
---|
title | Manual 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 |
---|
title | Load 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 |
---|
|
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 |
---|
language | yml |
---|
title | docker-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 |
---|
language | yml |
---|
title | docker-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 |
---|
language | text |
---|
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 |
---|
title | default.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 |
---|
|
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.