How to: Set up a frontend app for sandbox testing using S3

Owned by Douglas Hall (Deactivated)
Last updated: Dec 08, 2020 by Rebecca Graber (Deactivated)

This is out of date. See How To Add an MFE to a Sandbox for more current information


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.

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

  1. Request a public certificate using AWS Certificate Manager in the AWS console.
  2. During the request process, choose DNS validation.
  3. 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.
  4. 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.

  1. Create a new web distribution using AWS Cloudfront in the AWS console.
  2. Set Origin Domain Name to the hostname of the sandbox you created e.g. douglashall.sandbox.edx.org.
  3. Set Origin Protocol Policy to HTTPS Only.
  4. Set Viewer Protocol Policy to Redirect HTTP to HTTPS.
  5. Set Allowed HTTP Methods to GET, HEAD, OPTIONS, PUT, POST, PATCH, DELETE.
  6. Set Forward Cookies to All.
  7. Set Query String Forwarding and Caching to Forward all, cache based on all.
  8. Set Alternate Domain Names to the desired subdomain of your custom domain e.g. lms.edxdev.org where edxdev.org is the custom domain you registered.
  9. Set SSL Certificate to Custom SSL Certificate and select the certificate that you created above.
  10. Click Create Distribution and wait for it to be deployed (this may take awhile).
  11. Go to AWS Route 53 in the AWS console.
  12. Edit the Hosted Zone you created above.
  13. Create a new Record Set for the subdomain you wish to use for the Cloudfront distribution created above.
    1. Set name to the subdomain you used above in the Alternate Domain Names field e.g lms.exdev.org.
    2. Set Alias to Yes.
    3. Set Alias Target to the Cloudfront distribution created above.
  14. You will now be able to access your sandbox using the custom subdomain you specified e.g. lms.edxdev.org.

Create S3 Bucket

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

  1. Create a new S3 bucket using the AWS console.
  2. The bucket name should match the subdomain you which to use to server your frontend app e.g. gradebook.goodtimes.org.
  3. You want to allow public access to the bucket, so uncheck all the options under "Public access settings for this bucket".
  4. Click Create Bucket.
  5. Edit the bucket properties.
    1. Set up Static Website Hosting.
    2. Enter index.html for both the Index document and Error document.
  6. Edit the bucket permissions.
    1. Create a bucket policy using the AWS Policy Generator.
      1. Choose S3 Bucket Policy from
      2. Set Principal to *.
      3. Select GetObject from Actions.
      4. Set Amazon Resource Name to your bucket's ARN with a /* at the end e.g. arn:aws:s3:::gradebook.edxdev.org/*
      5. Click Add Statement.
      6. Click Generate Policy.
    2. Copy and paste the generated policy to the bucket policy editor.
    3. Click Save.

Deploy Frontend App

Use the AWS CLI to sync your built frontend app to your new S3 bucket.


$ aws s3 sync dist/ s3://gradebook.edxdev.org

Create Cloudfront Distribution for S3 Bucket

We will create a Cloudfront distribution in order to server our frontend app from the S3 bucket over SSL.

  1. Create a new web distribution using AWS Cloudfront in the AWS console.
  2. Set Origin Domain Name to the S3 bucket you created above.
  3. Set Origin Protocol Policy to HTTPS Only.
  4. Set Viewer Protocol Policy to Redirect HTTP to HTTPS.
  5. Set Alternate Domain Names to the custom subdomain for your frontend app e.g. gradebook.edxdev.org.
  6. Set SSL Certificate to Custom SSL Certificate and select the certificate that you created above.
  7. Set Default Root Object to index.html.
  8. Click Create Distribution.
  9. Edit the distribution and to to the Error Pages tab.
  10. Click Create Custom Error Response.
  11. Set HTTP Error Code to 404: Not Found.
  12. Set Customize Error Response to Yes.
  13. Set Response Page Path to /index.html.
  14. Set HTTP Response Code to 200: OK.
  15. Click Yes, Edit.
  16. Wait for the distribution to be deployed (this may take awhile).
  17. Once the distribution has been deployed you can continue with setting up DNS for your frontend app's subdomain below.

Set Up DNS for Frontend App

Finally, we will set up DNS for the custom subdomain we wish to use for our frontend app.

  1. Go to AWS Route 53 in the AWS console.
  2. Edit the Hosted Zone you created above.
  3. Create a new Record Set for the subdomain you wish to use for your frontend app.
    1. Set name to the subdomain you used above in the Alternate Domain Names field of the Cloudfront distribution created for your frontend app above e.g gradebook.exdev.org.
    2. Set Alias to Yes.
    3. Set Alias Target to the Cloudfront distribution created above.
  4. You will now be able to access your frontend app using the custom subdomain you specified e.g. gradebook.edxdev.org.

Add Frontend Hostname to Configuration on Backend Sandbox

You will need to edit the settings of your backend services on the backend sandbox to allow cross domain requests to be made to them.

  • Add your frontend hostname to the CORS_ORIGIN_WHITELIST setting on each of the services you wish to make API requests to.
  • In /edx/app/edxapp/lms.env.json, set the value of CROSS_DOMAIN_CSRF_COOKIE_DOMAIN to the hostname you used for the backend proxy Cloudfront distribution created above e.g. douglashall.edxdev.org.
  • Add your frontend hostname to the LOGIN_REDIRECT_WHITELIST setting in /edx/app/edxapp/lms.env.json.
  • In /edx/app/edxapp/lms.env.json, set the value of SESSION_COOKIE_DOMAIN to the custom domain you created above e.g. edxdev.org.
  • Restart each of the services for which you modified settings.

https://medium.com/@itsmattburgess/hosting-a-https-website-using-aws-s3-and-cloudfront-ee6521df03b9

https://medium.com/@sbuckpesch/setup-aws-s3-static-website-hosting-using-ssl-acm-34d41d32e394