Docker Deployment v1.0.0
December 2020: On behalf of the Ed-Fi community, we are pleased to announce the release of Ed-Fi-ODS Docker Deployment 1.0.0 which includes support for deploying the latest Ed-Fi ODS / API v5.1.0 version.
The Ed-Fi ODS Docker deployment scripts install and configure components of the Ed-Fi ODS / API on Docker containers. The Docker Compose files provided automate the numerous configuration steps required to get the ODS / API up and running on Linux containers backed by PostgreSQL 11. These scripts can be used for scenarios where a default ODS / API is needed without extensions or customizations which is better accommodated with a full source-code installation. The following configurations are supported out of the box.
Shared Instance Configuration
Deploying to Docker Containers
Docker Containers have the added benefit of running anywhere (e.g., VMs, on premises, in the cloud), which is a huge advantage for both development and deployment. It has been adopted by leading cloud providers, including, Google Cloud, Amazon Web Services (AWS), and Microsoft Azure. For simplicity, the steps below describe how to install on ODS / API on Docker Desktop.
Step 1. Download the Source Code or Clone the Repo
The Ed-Fi ODS Docker deployment source code is contained in the Ed-Fi repository hosted by GitHub. A link to the repository is provided in the download panel on the right. You can either clone the repository or download the source code as a ZIP file.
Step 2. Set up Docker Environment
To work with the material in this repository, set up a Docker environment by referring to the article Set Up Your Docker Environment.
Step 3. Setup Your Environment Variables
Configure your deployments using environment file. The repository includes .env.example, which lists the supported environment variables. Copy .env.example file and name it .env. Update the values as desired. A sample .env setting is provided below as an example and not be used as is in your deployment.
Compose supports declaring default environment variables in an environment file named .env, placed in the folder where the docker-compose command is executed (current working directory). If you desire a different different name or location, the following command can be used with docker-compose during deployment.
Step 4. Choose Your Deployment Options
The Docker Compose file for sandbox environment installs three primary Ed-Fi applications in separate containers behind NGINX proxy:
- Ed-Fi ODS / API
- Sandbox Admin
EdFi_Admin, EdFi_Security and ODS sandboxes are installed on one PostgreSQL 11 container.
If you desire to deploy sandbox environment, navigate to the root directory of docker deployment scripts and run the following script:
The Docker Compose for Shared Instance environment installs the following behind NGINX proxy.
- Ed-Fi ODS / API
- Ed-Fi ODS / API Admin App (will be available in future)
EdFi_Admin and EdFi_Security databases are installed on one PostgreSQL 11 container. EdFi_Ods database is installed on a separate PostgreSQL 11 container.
Alternatively, you can execute sandbox-env-up.ps1 or shared-instance-env-up.ps1 PowerShell scripts if deploying on Windows host.
These compose files pull down the images from Docker Hub. The repository contains two additional compose files compose-sandbox-env-build.yml and compose-shared-instance-env-build.yml that work with the Dockerfiles directly for customizations.
Step 5. Provide SSL certificate
The deployments require a valid SSL certificate to function. A self-signed certificate can be used for a Non-Production environment. The repository includes generate-cert.sh script that can be used to generate a self-signed certificate and place it in folder
Ed-Fi-ODS-Docker/Web-Gateway-Sandbox/ssl (for sandbox mode) to be used by the running Gateway container.
If deploying on local Windows host, you will either need Git Bash or WSL to run generate-cert.sh.
Using Git Bash
- Start a Git Bash Session
- Run the following commands:
- Enable WSL and install a Linux from the Microsoft Store.
- Start a WSL session.
- Change directory to the Web-Gateway (Web-Gateway-Sandbox) folder under Ed-Fi-ODS-Docker repository folder.
- Convert the script from CRLF to LF endings.
- Run script generate-cert.sh (i.e., ./generate-cert.sh).
Step 6. Verify Your Deployments
Open you Docker Desktop instance and view running container instances. The following image shows sandbox deployment:
You can also verify deployed applications by browsing to:
- Swagger UI : https://localhost:5000/
- ODS / API : https://localhost:5001/
- Sandbox Admin : https://localhost:5002/
Step 7. Accessing Log Files
The ODS/API and SandboxAdmin write logs to a mounted folder within their docker containers. The environment file described in the Step 3 lets you configure log location for easy access. For example, you could set LOGS_FOLDER variable to c:/tmp/logs for windows hosts or to ~/tmp/logs for Linux and MacOS hosts.
Tearing down Docker Deployments
If deployed as a sandbox environment, navigate to the root directory of Docker deployment scripts and run the following script:
If deployed as a shared instance environment, navigate to the root directory of Docker deployment scripts and run the following script:
Using -v option with the docker-compose will remove volumes declared in the compose file, which includes the database volumes. Do not use that option if you intend to keep the data in the ODS.
Alternatively, you can execute sandbox-env-clean.ps1 or shared-instance-env-clean.ps1 PowerShell scripts if you are using Windows host.
- No labels