How to: Set up a frontend app for sandbox testing

This how-to describes how to serve your frontend app from an AWS S3 bucket and configure it to use an edX sandbox as it's backend. The instructions here assume that you already have a personal AWS account created with credentials configured for the AWS CLI.

NOTE: You will incur charges to your personal AWS account by using these instructions. If you are using this set up strictly for sandbox testing, the charges should be minimal (~ cents per month). You will also need to buy a custom domain.

Deploy Sandbox

First, we want to deploy an edX sandbox which will be used as our backend using the sandbox provisioning job at https://tools-edx-jenkins.edx.org/job/Sandboxes/job/CreateSandbox/build?delay=0sec. Be sure to include all of the services you will need for your frontend app (i.e. LMS, Studio, ecommerce, etc.).

Purchase Custom Domain

We will need our own custom domain so that cookies can be shared across the frontend and backend. Go to godaddy.com or the domain registrar of your choice to purchase your custom domain.

Set Up Custom Domain in Route 53

We will use AWS Route 53 for DNS of our custom domain.

Create a new public Hosted Zone for your custom domain using AWS Route 53.

Create SSL Certificate

Frontend apps redirect users to the LMS login page for authentication. When redirecting to the LMS login page, frontend apps include a "next" query parameter whose value can be a URL which the LMS will use to redirect the user once they have been authenticated. The LMS requires the "next" parameter value to be an HTTPS URL. This requires us to serve our frontend apps over SSL. Luckily, AWS makes it easy to request a certificate that can be used to serve our resources over SSL.

Request a public certificate using AWS Certificate Manager in the AWS console.
During the request process, choose DNS validation.
The request process will ask you to add a CNAME record to Route 53 in order to confirm your ownership of the domain. Do as instructed.
Once the certificate has been validated by AWS, you will be able to use it to serve resources over SSL.

Proxy Sandbox Requests Using Your Custom Domain

We will want to be able to make requests to our sandbox using our custom domain so that cookies can be shared with the frontend app. We will use AWS Cloudfront to proxy requests to the edX sandbox.

Create a new web distribution using AWS Cloudfront in the AWS console.
Set Origin Domain Name to the hostname of the sandbox you created e.g. douglashall.sandbox.edx.org.
Set Origin Protocol Policy to HTTPS Only.
Set Viewer Protocol Policy to Redirect HTTP to HTTPS.
Set Allowed HTTP Methods to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
Set Forward Cookies to All.
Set Query String Forwarding and Caching to Forward all, cache based on all.
Set Alternate Domain Names to the desired subdomain of your custom domain e.g. lms.goodtimes.org where goodtimes.org is the custom domain you registered.
Set SSL Certificate to Custom SSL Certificate and select the certificate that you created above.
Click Create Distribution and wait for it to be deployed (this may take awhile).
Once the distribution has been deployed you will be able to access your sandbox using the custom subdomain you specified e.g. lms.goodtimes.org.

Create S3 Bucket

We will sync our built frontend app with an S3 bucket from which it will be served to end users.

Create a new S3 bucket using the AWS console.
The bucket name should match the subdomain you which to use to server your frontend app e.g. gradebook.goodtimes.org.
You want to allow public access to the bucket, so uncheck all the options under "Public access settings for this bucket".
dldPublic access s for this bucket