Page History

Prerequisite Steps

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

Get started

Once you have satisfied those prerequisites,

1. Download the ZIP file from the Ed-Fi Exchange to your laptop and unpack it. (You'll use these files later.)
2. Log into the AWS Management Console.
   1. IAM accounts: Log in at https://accountname.signin.aws.amazon.com/console.
   2. Root accounts: Log in at https://console.aws.amazon.com/.
3. Click Services ≫ > CloudFormation.
   
4. 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.
   
   
5. Click the Create New Stack button.
   
6. 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.
   
   
7. Fill out the Specify Details form using the following steps for each field:
   1. Stack Name: "Ed-FiODSAPIv2-5".
   2. EdFi S3 Bucket and EdFi S3 Bucket Region: Leave this default value.
   3. 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.)
   4. Selected Instance Type: Economy
   5. 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.)
   6. Finally, click Next.
8. On the following Options screen, simply click Next.
9. 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.
10. Click Next.
11. Monitor the Outputs tab once active and use the WebServerSetupStatusURL which indicates completion of the build.
12. 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

1. Open a Command Prompt on your laptop.
2. Using the WebAPIEndpointURL from your Outputs tab, e.g. WebAPIEndpointURL = https://ed-fiodsa-odsapilo-fwkv3f9r7r81-1078570745.us-east-2.elb.amazonaws.com/EdFi.Ods.WebAPI
3. $ signs indicate things to substitute (copy and paste) on the command line

curl {$WebAPIEndpointURL}/oauth/authorize -d "Client_id=productionAPIkey&Response_type=code"
"{'Code':$WebAPIKey'}"
curl {$WebAPIEndpointURL}/oauth/token -H "Content-Type: application/json" -d "{'Client_id':'productionAPIkey','Client_secret':'productionAPIkeySECRET','Code':'{$WebAPIKey}','Grant_type':'authorization_code'}"
"{'Code':'$WebAPIAuthCode'}"
curl {$WebAPIEndpointURL}/api/v2.0/2017/schools -H "Authorization: Bearer {$WebAPIAuthCode}"

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.

<detail here>

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:

1. 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.
   
2. Enter "EdFi Key Pair" for the Key Pair to be created. Then click Create.
   
   
3. 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.
4. 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 Windows: Install the Git for Windows package which includes a Git Bash command line and the OpenSSL binaries. You can also download the openssl binaries from a third party.

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.

1. 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"
2. Import the certificate and private key (from the two *.pem files created by the command in the previous step) to the AWS Certification Manager

3. Returning to the AWS Management Console, click Services ≫ Certificate Manager in the section "Security & Identity".

4. Next, click the button Import a certificate.

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

   2. Certificate Private Key: Likewise, copy and paste the yourPrivateKey.pem file's contents into this text box.

   3. Certificate Chain: Leave this text box blank.

   4. Click the button Review and Import.

5. Click Import on the resulting screen.

6. Finally, RECORD the ARN value from the resulting screen. This is the text value that must be entered into the CloudFormation Template.