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​

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.0.1"

    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.0.1

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

    • 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

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

# This line is only necessary when you are using a self-signed certificate.
NODE_EXTRA_CA_CERTS=/app/ssl/your-production-cert.crt

# Administrator credentials
KEYCLOAK_ADMIN=admin

# 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/
note

Important: The VITE_IDP_ACCOUNT_URL value may differ from your Keycloak admin console URL. This should point to the account management interface (/auth/realms/{realm-name}/account/), not the admin console. Ensure this matches your actual Keycloak realm configuration and domain.

  • 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​