Skip to main content
Ed-Fi.orgDocsCommunityAcademy

Docker Compose Installation

Docker provides the easiest deployment method with consistent environments across platforms. OCI-compliant containers provide a consistent deployment experience across many platforms, including Docker Desktop, Kubernetes, and other services. The following quick start instructions demonstrate application startup in Docker. They illustrate how to configure the applications, including environment variables, persistent storage, and networking. These notes can also serve as a template for building your own deployment in the container runtime engine of your choice, whether on-premises or in the Cloud.

note

This is one of three alternative installation paths. If you instead want to host the Admin App on Windows IIS or on a Unix-like server, see Windows IIS Installation or Unix-like Systems Installation.

Docker Installation Guide for Ed-Fi Admin App​

This guide explains how to install and run the Ed-Fi Admin App using Docker Compose and the provided start-services.ps1 script. It covers both building images locally and pulling pre-built images from Docker Hub, as well as environment variable configuration.

Docker Prerequisites​

Database engine​

The Docker Compose stack supports both PostgreSQL and SQL Server — you need only one. PostgreSQL is the default. To use SQL Server instead, set DB_ENGINE=mssql in .env, uncomment the MSSQL_* variables there (MSSQL_SA_PASSWORD, MSSQL_ACCEPT_EULA=Y), switch DB_SECRET_VALUE to its SQL Server form, and start the stack with the -MSSQL switch:

compose/start-services.ps1 -MSSQL

Quick Start​

  1. Clone the Admin App repository:

    Reference compose folder from Admin App

    tip

    If you have not cloned the Admin App repository, do so and ensure you are in the correct directory.

    note

    Always install from a stable release tag, not the default main branch (which reflects active development). Visit the Releases page to find the latest stable release tag, then use it in the command below.

    # Replace the TAG value with the latest release from the Releases page
    $TAG = "v4.1.0"

    git clone --branch $TAG --depth 1 https://github.com/Ed-Fi-Alliance-OSS/Ed-Fi-AdminApp.git

  2. Create environment configuration:

    cp .env.example .env
    # Edit .env file with your specific settings

    The .env.example file is located in the compose directory.

  3. Generate SSL certificates:

    # On Linux/WSL/Git Bash:
    cd ssl && ./generate-certificate.sh && cd ..
    note

    Only needed if you don't already have a certificate pair to use.

  4. Start core and Admin App services:

  • Using Pre-Built Images: The recommended way to run the Admin App is to use the official images from Docker Hub.

    • Frontend: edfialliance/admin-app-fe:v4.1.0

    • API: edfialliance/admin-app-api:v4.1.0

    • Open PowerShell in the compose directory:

      cd ./compose
      tip

      If you encounter permission issues, run PowerShell as Administrator.

    • Run the following command to start all services:

      ./start-services.ps1

      This script will pull the required images and start the containers defined in adminapp-services.yml and edfi-services.yml.

  • Building Images Locally (Advanced):

    If you want to build the images from source (for development or customization), Ensure you have cloned the repository and installed all dependencies. In the compose directory, run:

    ./start-services.ps1 -Rebuild

    This will build the admin-app-fe and admin-app-api images locally before starting the containers.

Environment Variables​

Deployment settings can be customized using environment variables. Define these variables in a .env file within the compose directory, or provide them directly to Docker Compose as needed.

For a complete list of available variables and their descriptions, see the Environment variables example file.

Example .env for Production​

# Use strong, unique passwords
POSTGRES_PASSWORD=your-secure-password
KEYCLOAK_ADMIN_PASSWORD=your-keycloak-password

# Database connection for the API. DB_PASSWORD must equal POSTGRES_PASSWORD
# (it is not filled in from it). For SQL Server, use the commented mssql form
# from .env.example instead, with MSSQL_DB_PASSWORD equal to MSSQL_SA_PASSWORD.
DB_SECRET_VALUE={"DB_HOST":"edfiadminapp-postgres","DB_PORT":5432,"DB_USERNAME":"postgres","DB_PASSWORD":"your-secure-password","DB_DATABASE":"sbaa"}

# Set production URLs
VITE_API_URL=https://yourdomain.com/adminapp-api
FE_URL=https://yourdomain.com/adminapp
MY_URL=https://yourdomain.com/adminapp-api

# Only needed when the app must trust a self-signed/private-CA certificate.
NODE_EXTRA_CA_CERTS=/app/ssl/your-cert.crt

# Administrator credentials
KEYCLOAK_ADMIN=admin

# Required secrets: the API refuses to start without them.
# Generate each value with: openssl rand -hex 32
SESSION_SECRET_VALUE=["your-session-secret"]
DB_ENCRYPTION_SECRET_VALUE={"KEY":"your-64-hex-char-encryption-key","IV":"unused"}
KEYCLOAK_EDFIADMINAPP_CLIENT_SECRET=your-keycloak-client-secret
KEYCLOAK_EDFIADMINAPP_DEV_CLIENT_SECRET=your-keycloak-dev-client-secret

# Keycloak hostname, when the stack is not served from localhost
KEYCLOAK_HOSTNAME=yourdomain.com
KEYCLOAK_HOSTNAME_PROTOCOL=https

# Verify TLS certificates on outgoing requests (default true)
SSL_VERIFICATION=true

# Audit log (default true); see the Getting Started overview
AUDIT_LOGGING_ENABLED=true

# Session lifetime in minutes (default 120)
DB_TTL_IN_MINUTES=120

# Frontend UI Configuration
VITE_STARTING_GUIDE=https://docs.ed-fi.org/reference/admin-app/configuration/global-administration-tasks
VITE_CONTACT=https://community.ed-fi.org/
VITE_APPLICATION_NAME="Ed-Fi Admin App"
VITE_IDP_ACCOUNT_URL=https://yourdomain.com/auth/realms/edfi/account/

# OIDC provider selector: the id of the `oidc` table row to sign in with
# (must match the redirect-URI callback id). On a fresh single-provider
# install this is 1.
VITE_OIDC_ID=1
warning

Some special characters are not currently supported in the database password (for example POSTGRES_PASSWORD, or MSSQL_SA_PASSWORD when using SQL Server). Use only letters, digits, and these symbols: ! $ ( ) * , - . _ ~. A password that includes other characters (for example @ : / ? # % & = ;, ", < >, |, or a space) can stop the API from connecting to the database at startup.

warning

The API refuses to start in production when SESSION_SECRET_VALUE, DB_ENCRYPTION_SECRET_VALUE, the database password, or the Keycloak client secrets are missing, blank, or still set to the sample values from .env.example.

  • SESSION_SECRET_VALUE is a JSON array of secrets, newest first. To rotate it, add the new secret at the front and keep the old one until existing sessions expire.
  • DB_ENCRYPTION_SECRET_VALUE.KEY must be 64 hexadecimal characters. It encrypts the stored environment credentials, so never change it once environments exist: the Admin App can no longer decrypt them with a different key.
note

SSL_VERIFICATION defaults to true. Set it to false only to reach upstream services with self-signed certificates during testing; it is not recommended in production. Prefer NODE_EXTRA_CA_CERTS to trust a private certificate authority.

note

Important: VITE_IDP_ACCOUNT_URL should point to your identity provider's end-user account-management page, not its admin console. It is provider-specific: Keycloak https://<host>/auth/realms/{realm}/account/, Microsoft Entra ID https://myaccount.microsoft.com/, Google Workspace https://myaccount.google.com/, Auth0 has no hosted account page (use the tenant URL as a placeholder or your own profile page). If you leave VITE_IDP_ACCOUNT_URL out of .env, Docker Compose falls back to https://localhost/auth/realms/edfi/account/, so set it for any deployment not served from localhost.

note

The bundled stack ships Keycloak as the example OIDC provider. Because the Admin App uses generic OIDC discovery, Microsoft Entra ID, Google Workspace, and Auth0 also work: set the provider values (issuer, clientId, clientSecret, scope) in packages/api/config/production.js-edfi (baked into the API image as production.js), rebuild with ./start-services.ps1 -Rebuild, and select it from the frontend with VITE_OIDC_ID.

note

For an external provider, the redirect/callback URI is <MY_URL>/api/auth/callback/<oidc-id> — with the Compose stack's default NGiNX proxy (all services served from https://localhost), that is https://localhost/adminapp-api/api/auth/callback/1.

  • SSL Certificates: Replace self-signed certificates with production certificates in a live environment.
  • Database: For reliability, consider using an external PostgreSQL instance in production.

Next steps​

A fresh install has no users, teams, or environments yet. The Global Admin Quick Start seeds that starter configuration, so it is the recommended next step.