Options and Prerequisites
(Highly Recommended) Prerequisites
|Bring a laptop!|
This lab is intended to be hands-on for everyone who attends, therefore all attendees are expected to bring a laptop.
Attendees will use their computer to either connect remotely to provided Virtual Machines to follow the steps in this lab, or use their own Windows laptop for those who are able to.
|Prepare your computer or your cloud environment!|
Some attendees will want to focus on an enterprise deployment while others will want to use the one of the options provided on the Ed-Fi Exchange for cloud deployments (AWS, Azure) or local install.
Azure tenancy prerequisite:
You can use an existing Azure subscription and login provided you are Co-Owner (Co-Admin is not sufficient)
Note that the free Azure subscription requires a credit card!
AWS tenancy prerequisite:
|AWS requires rights to add permissions to the global <updating>|
Use a provided virtual machine to:
Use your own workstation to:
"I'm supposed to deploy something..?"
(or - Governance is the Answer. What was the question?)
The Ed-Fi ODS/API is a reference implementation of the Ed-Fi Universal Data Model and API specification. It is provided as downloadable source code on GitHub, using Microsoft .NET, SQL Server, and appropriate deployment scripts for an enterprise Windows environment. The members of the community built and shared deployment artifacts for compatible cloud providers in addition to a standalone installer package, all of which are hosted on the Ed-Fi Exchange. During this lab, you will choose one of these approaches and deploy your own Ed-Fi ODS/API.
Becoming an effective Ed-Fi Agency
Becoming an effective Ed-Fi Agency means adopting a mindset across the entire district of:
- Focusing on value for instructors, curriculum, assessment, and leadership teams
- Starting with the ends in mind and delivering on promises
- Communicating with stakeholders, including vendors, partners, administrators, and your community.
- Sharing your experiences, good or bad.
These are the foundation of governance that education agencies often look to their IT departments to implement. However, governance is not an IT process, it is an institutional mindset of implementing patterns of success.
Explaining data interoperability to your instructors and administrators
The hardest job for a technical team member is convincing your instructional or assessment staff of why they should care about the Ed-Fi Standard, about how a common language to work with other teams helps get what they want done. Until you can show them, you'll have to use some specific examples of how the lack of interoperability wastes their time and limits their ability to act.
Deployment scenarios and example solutions
The Ed-Fi ODS/API is a multi-tenant solution which can be deployed for statewide use or use by individual districts. For the purposes of this lab, we'll focus on setting up a development environment for you to use while developing and testing API connections from your source systems or ETL processes.
Hands-On with the Ed-Fi ODS
Connecting to your development environment
Virtual Machines are provided during the live lab to make it easy to dive in. These VMs are provided with the following software: Window 10, Microsoft SQL Server 2014 Developers Edition, Visual Studio 2017 Community, Git client, and any dependencies.
Standard development build
Go directly to the Getting Started Guide if you want to go for it with a local install on your laptop.
If you want to use the VM to build and play, follow along here
- Connect to your VM
- All of the steps to download and configure your development environment, including installation of software prerequisites SQL Server 2014 and Visual Studio 2015, have been done.
- The projects in the Ed-Fi-ODS-Implementation repository are configured to run the desktop version of Internet Information Server (i.e., IIS Express). This server is installed with Visual Studio and facilitates easy debugging with minimal configuration.
- Confirm the startup projects are set, right-click on the
- You are ready to run or debug the Ed-Fi ODS / API.
- To run the Ed-Fi ODS / API without debugging, press Ctrl+F5.
- To interactively debug the Ed-Fi ODS / API solution, press F5 (or press Start in the Standard Toolbar).
- The first time you build the solution, you may get a build error related to the Ed-Fi-Common project. If this occurs, simply building the solution again will generally result in a successful build.
The solution builds and starts each of the projects that were added to the startup projects list. Each web application starts an instance of IIS Express. By default, the websites are configured according to the following table:
Ed-Fi ODS API
Ed-Fi ODS API Documentation
Congratulations! You are up and running!
Cloud installation on Azure
If you encounter any errors the Troubleshooting and Tuning an Installation guide may be able to help diagnose and correct.
Know your Azure login and setup:
- Download the Cloud ODS and API
- Open PowerShell in Admin mode and setup your workstation correctly with AzureRM:
- You may need to "Unblock" the ZIP file you downloaded. To do that:
- In Windows Explorer, right-click each of the downloaded ZIP files and select Properties.
- On the General tab, press Unblock to allow the contents of the contained scripts to execute properly.
- Note that Windows 10 will display an "Unblock" checkbox only if necessary. If you don't see that checkbox then unblocking is not necessary.
- From the place where you downloaded the package, (unpack it and) run:
- And in a short bit:
- Copy the URL shown in the PowerShell window:
- And launch the Admin App to continue setup. (Click the button to continue of course.)
- Now get your license
Congratulations! You are up and running!
Cloud installation on Amazon AWS
There are two important prerequisites that must be done before you can provision your Ed-Fi ODS/API environment.
First, you need an encryption key pair for administrative access to your AWS EC2 deployment. If you haven't already setup your AWS EC2 key pair, follow that step below.
Second, you must have SSL certificates available in your AWS Certificate Manager for use by the Ed-Fi endpoints. It is possible to use a self-signed certificate for initial setup, but due to the high security requirements of AWS, you will not be able to use the Admin App, but it will be installed. Once you have a properly configured certificate, the Admin Panel will function normally.
You should also make sure that if you are using the AWS IAM-based login, that your IAM account has sufficient privileges to create S3 "storage buckets" and to create EC2 instances (i.e., servers).
Once you have satisfied those prerequisites,
- Download the ZIP file from the Ed-Fi Exchange to your laptop and unpack it. (You'll use these files later.)
- Log into the AWS Management Console.
- Click Services > CloudFormation.
- At the top right-hand corner, click the region selector, and choose one of the regions in the United States to hold all of your creation.
- Click the Create New Stack button.
- Select Upload a template to Amazon S3 radio button and click Choose File. Browse to the “odsnetwork.template” CloudFormation template file and upload. Click the button Next.
- Fill out the Specify Details form using the following steps for each field:
- Stack Name: "Ed-FiODSAPIv2-5".
- EdFi S3 Bucket and EdFi S3 Bucket Region: Leave this default value.
- Key Name: (drop-down menu) The name of the EC2 Key Pair in your AWS Account to secure all server passwords in the system. (Problems? See the step-by-step procedure for creating an EC2 Key Pair below.)
- Selected Instance Type: Economy
- SSL.CertId: Specify the AWS Resource Number (e.g., ars:aws:acm:… ) that identifies the X.509 Secure Socket Layer certificate used to encrypt/decrypt HTTPS communications.
This identifier can be found in the AWS Certification Manager. (Problems? See the step-by-step instructions for creating and storing an SSL certificate below.)
- Finally, click Next.
- On the following Options screen, simply click Next.
- On the following Review screen, scroll to the bottom of the page, and check the checkbox to allow permission for the build.
After you have launched your system, you are free to delete this role via the AWS Management Console ≫ Services ≫ IAM ≫ Roles ≫ ServerS3andRDSRole ≫ Delete.
- Click Next.
- Monitor the Outputs tab once active and use the WebServerSetupStatusURL which indicates completion of the build.
- Once that displays "The system is ready for use", congratulations! you have provisioned an Ed-Fi ODS/API !
Refer to the Outputs tab
WebAPIEndpointURL - The API URL you'll test next.
ODSAPIKeySecret - The Initial authentication credentials. (Normally you'd change these immediately after testing in database table EdFi_Admin.dbo.ApiClients.)
JumpServerPublicDNSName You will need to connect to this machine in order to use the Admin App, which runs on the BuildServer. The Build Server address can be found under CloudFormation service >> Stacks >> stack-name ≫ Instances.
Smoke test of your Ed-Fi ODS/API
- Open a Command Prompt on your laptop.
- Using the WebAPIEndpointURL from your Outputs tab, e.g. WebAPIEndpointURL =
- $ signs indicate things to substitute (copy and paste) on the command line
If you see a list of schools, congratulations! Your Ed-Fi ODS is up and running!
Connect to the Admin App
Locate the Jump Server DNS Name and connect to that using RDP.
Connect from the Jump Server to the Build Server. You can find the Build Server in the list of EC2 machines.
On the build server, you can access the Admin App locally: https://localhost/EdFi.Ods.AdminApp.Web
Optional setup tasks
Setting up the EC2 Key Pair
To remotely log into the Windows servers in your Ed-Fi ODS system, you will need a user name and password with administrative-level access. The user name is always administrator. The password, however, is randomly generated, and must be retrieved from the EC2 Service Panel using something secret that you possess - the private key of an EC2 Key Pair. Let's create a key pair:
- In the AWS Management Console, ensure the Region Selector in the upper-right corner is the same region in which you will launch your Ed-Fi ODS network. Then, click Services, then click EC2, then click Key Pairs, then click Create.
- Enter "EdFi Key Pair" for the Key Pair to be created. Then click Create.
- The private key is automatically downloaded to your browser as a *.pem file which is a text file containing the private key. When prompted for this key later, you can paste the text or browse to and upload the *.pem file.
- You will use the private key you downloaded when you click the Connect / Action button (Management Console >> Services >> EC2) to retrieve the administrator password and use it to log into the system.
Creating a Self-Signed Certificate to test the API
Reminder: self-signed certificates can't be used by the Admin App without configuring the IIS application server to ignore SSL (Usually a bad idea!)
Note for non-Windows: OpenSSL is normally installed by default on most systems. Use your normal system package manager to install OpenSSL if it is not installed.
- Substituting the appropriate region for "us-east-2", use this command at a prompt where OpenSSL is installed:
openssl req -x509 -sha256 -newkey rsa:2048 -keyout yourPrivateKey.pem -out yourNewCertificate.pem -days 365 -nodes -subj "/C=US/ST=Texas/L=Austin/O=Company Name/OU=Org/CN=*.us-east-2.elb.amazonaws.com"
- Import the certificate and private key (from the two *.pem files created by the command in the previous step) to the AWS Certification Manager
Returning to the AWS Management Console, click Services ≫ Certificate Manager in the section "Security & Identity".
Next, click the button Import a certificate.
Certificate Body: Using Notepad or other text file editor, open the yourNewCertificate.pem certificate file and copy and paste its contents into the Certificate Body text box.
Certificate Private Key: Likewise, copy and paste the yourPrivateKey.pem file's contents into this text box.
Certificate Chain: Leave this text box blank.
Click the button Review and Import.
Click Import on the resulting screen.
Finally, RECORD the ARN value from the resulting screen. This is the text value that must be entered into the CloudFormation Template.