Hyrax AWS Cloud Formation Template

AWS Cloud Formation Templates for AMS (Archival Management System)

Create a brand spankin new stack that can run AMS

Use the ams.new_app.json CloudFormation template. This will create a bunch of AWS resources used to run AMS.

NOTE: The stack costs $$$ when it's running so make sure you have approval first! When creating a new stack, AWS provides a cost estimate. Right now (Dec 2020) it costs about $140/month.

What you get

If successful, you'll have a fully functional stack of AWS resources capable of running the AMS web app.

Steps

1. Make sure you have the latest version of ams.new_app.json from this repository saved to your local machine.
2. Log into AWS Management Console.
3. Navigate to CloudFormation.
4. Click "Create stack" >> "With new resources".
5. Under "Prerequisite - Prepare template" select "Template is ready".
6. Under "Specify template" select "Upload a template file".
7. Click "Choose File" and select your local copy of ams.new_app.json from step 1, and then click "Next".
8. Enter a Stack Name, enter values for the parameters:
   1. All password fields are required.
   2. ServerName is used for enabling HTTPS and should match the site's domain for verification. If not enabling HTTPS, the default value is fine.
   3. All other default values should work, but you can adjust them as needed.
   4. Click "Next" when finished.
9. For the "Configure stack options" and "Advanced options", defaults will suffice, but adjust as needed, and click "Next" when finished.
10. Review the stack details to make sure it's what you want. To go back, click the "Previous" button at the bottom.
11. If the stack looks good to go, check the checkbox labeled with "I acknowledge that AWS CloudFormation might create IAM resources."
12. Click "Create Stack". This will kick of an asynchronous process to build the stack. Check the "Events" tab to see the progress. When you see an event in the list whose "Logical ID" is your stack name, and the "Status" is "CREATE_COMPLETE", then the stack is ready.
13. Deploy Code
    1. In the AWS Management console, navigate to CodeDeploy.
    2. In the left menu, click "Applications".
    3. Click the AWS "Application" that was created with the CloudFormation template (it should be named the same as your stack).
    4. Click deployment group for the app (there should be only 1 and be named the same as the stack name, but with "-DG" suffix appended.
    5. Click the "Create Deployment" button.
    6. On the "Create Deployment" screen:
       1. Enter the deployment group that was created as part of the stack. It should be named the same as the stack, with a "-DG" suffix.
       2. Select the "My application is stored in Github" option.
       3. Enter the Github token name.
       4. Enter the repository name: "wgbh-mla/ams".
       5. Enter the commit hash of the commit you want to deploy. **NOTE: Due to a branching convention we never truly followed, we do not currently use the master branch, but rather the the develop branch, thus we typically deploy the most recent commit from develop. This may change, so be sure to consult with developers if you are unsure which branch/commit represents the latest code.
       6. Add an optional description.

Restore AWS stack using data from snapshot backups

Use the ams.restore_from_backups.json to restore the AMS

What you get

If successful, you'll have a fully functioning AMS app with data rolled back to the point-in-time that the snapshots were taken.

Steps

1. Make sure you have the latest version of ams.restore_from_snapshot.json from this repository saved to your local machine.
2. If you're recreating from an existing instance, ssh in to the active EC2 instance hosting Solr and Fedora to copy their data directories.
3. The Fedora data directory is currently located at: /mnt/fedora-data
4. The Solr data directory is currently located at: /var/solr/data/ams/data
5. Log into AWS Management Console.
6. Navigate to RDS
7. Click on "DB Instances"
8. Create snapshots of the MySQL RDS instances for Rails and Fedora by clicking on "Actions" >> "Take Snapshot"
   1. Copy the Amazon Resource Names (ARNs).
   2. Edit your local version of ams.restore_from_snapshot.json
      1. Enter the Rails DB ARN where it says: "REPLACE WITH ARN OF RAILS RDS DB SNAPSHOT"
      2. Enter the Fedora DB ARN where it says: "REPLACE WITH ARN OF FEDORA RDS DB SNAPSHOT"
9. Navigate to EC2
10. Select the EC2 instance for Fedora
11. Click on "Actions" >> "Image and templates" >> "Create Image"
    1. Defaults are fine.
    2. Click on "Create Image"
    3. Copy the AMI ID from the success message (should look like: ami-xxxxxxxxxxxxxxxxx)
       1. You can also get it from the EC2 interface by clicking on AMIs and finding it by AMI Name
    4. Edit your local version of ams.restore_from_backups.json
       1. Enter the AMI ID where it says: "REPLACE WITH IMAGE ID OF AMI CREATED FROM SNAPSHOT OF DataInstance EC2 ROOT VOLUME"
12. Navigate to CloudFormation.
13. Click "Create stack" >> "With new resources".
14. Under "Prerequisite - Prepare template" select "Template is ready".
15. Under "Specify template" select "Upload a template file".
16. Click "Choose File" and select your local copy of ams.restore_from_backups.json from step 1, and then click "Next".
17. Enter a Stack Name, enter values for the parameters:
    1. All password fields are required.
    2. ServerName is used for enabling HTTPS and should match the site's domain for verification. If not enabling HTTPS, the default value is fine.
    3. All other default values should work, but you can adjust them as needed.
    4. Click "Next" when finished.
18. For the "Configure stack options" and "Advanced options", defaults will suffice, but adjust as needed, and click "Next" when finished.
19. Review the stack details to make sure it's what you want. To go back, click the "Previous" button at the bottom.
20. If the stack looks good to go, check the checkbox labeled with "I acknowledge that AWS CloudFormation might create IAM resources."
21. Click "Create Stack". This will kick of an asynchronous process to build the stack. Check the "Events" tab to see the progress. When you see an event in the list whose "Logical ID" is your stack name, and the "Status" is "CREATE_COMPLETE", then the stack is ready.
22. Deploy Code
    1. In the AWS Management console, navigate to CodeDeploy.
    2. In the left menu, click "Applications".
    3. Click the AWS "Application" that was created with the CloudFormation template (it should be named the same as your stack).
    4. Click deployment group for the app (there should be only 1 and be named the same as the stack name, but with "-DG" suffix appended.
    5. Click the "Create Deployment" button.
    6. On the "Create Deployment" screen:
       1. Enter the deployment group that was created as part of the stack. It should be named the same as the stack, with a "-DG" suffix.
       2. Select the "My application is stored in Github" option.
       3. Enter the Github token name.
       4. Enter the repository name: "wgbh-mla/ams".
       5. Enter the commit hash of the commit you want to deploy. **NOTE: Due to a branching convention we never truly followed, we do not currently use the master branch, but rather the the develop branch, thus we typically deploy the most recent commit from develop. This may change, so be sure to consult with developers if you are unsure which branch/commit represents the latest code.
       6. Add an optional description.

SSL

The Cloudformation template includes setup that prepares the AMS web server for encryption with Certbot. As you are creating a new stack or restoring from the old do the following:

1. As you are setting the Parameters when launching a stack from a Cloudformation template, set the ServerName so that it matches the domain of your site.
2. Creating the stack via the Cloudformation template.
3. Deploy the code via CodeDeploy.
4. SSH to the web server.
5. Run sudo certbot to get the certificate.