Overview
This page documents the steps and tools needed to build the Voices in Biotech Project. Many of these will be broadly applicable to other Voices projects.
Software:
The Voices project uses the following software components
...
All of these components are used on the server and are automatically set up with the ansible command creates_voices.yml see the Ansible README for command details.
AWS Services:
The Voices project uses the following AWS services to manage and run the site
...
A key issue is that the Voices project is managed separately. See the AWS page for details on switching accounts to the Community History Project account. You must be in the correct account for all of the steps.
Setup:
Build server
Make sure you are on the most recent ansible-inventory. Follow the instructions in the README to build a voices server.
Once the server is built, go to AWS EC2 and find the Elastic Address section. Go there and assign the staging or production elastic IP to the newly built server.
Create S3 Bucket for Website
This follows instructions from (https://docs.aws.amazon.com/AmazonS3/latest/dev/HowDoIWebsiteConfiguration.html) which detail steps from the console.
Create an S3 bucket with the name of the site (i.e. voices.sciencehistory.org) (you should also see this name in the ansible var file for the server you just built)
Under properties to Static Website Hosting to “Use this Bucket to Host a Website”
The index document should be index.html
The error document should be 404.html
Under Permissions make sure Block Public Access (and all subsections) are set to Off
In Bucket Policy under Permissions follow the example under Step 2 (https://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteAccessPermissionsReqd.html) using our bucket name instead of Example
Import SSL Cert
This should only need to be done when we renew our SSL certs or if we change them. We are not using Amazon’s certificate creation service so we will need to import ours after making some changes to the format to work with AWS.
Editing Certificates
Amazon’s certificate manager requires PEM formatted keys. You will need the ssl key, intermediate certificate, and wildcard certificate.
For the wildcart certificate run
| Code Block |
|---|
openssl x509 -in CERTFILE -out CERTFILE.pem |
For the key run
| Code Block |
|---|
openssl rsa -in KEYFILE -out KEYFILE.pem |
The intermediate certificate is a bit trickier. OpenSSL’s default command doesn’t handle the three certificate chain well. So make 3 copies of the CA cert labeled 1-3 and in each one remove the other two certs. Then run
| Code Block |
|---|
openssl x509 -in CERTFILE-CA1.cert -outform PEM -out CERTFILE
-CA1.pem
openssl x509 -in CERTFILE-CA2.cert -outform PEM -out CERTFILE
-CA2.pem
openssl x509 -in CERTFILE-CA3.cert -outform PEM -out CERTFILE
-CA3.pem
cat CERTFILE-CA1.pem CERTFILE-CA2.pem CERTFILE-CA3.pem > CERTFILE-CA.pem |
Importing Certificates
Log onto AWS, and go to the Certificate Manager.
Select the Import a certificate button
Past the certificate in the certificate body, key in the key, and newly combined CA chain in the chain section.
Name and save the certificate
Create Cloudfront CDN
This is required since S3 website endpoints do not support SSL.
Open AWS Console and go to Cloudfront
Select the Create Distribution button
Choose the Web delivery method button
For Origin domain name DO NOT USE THE AUTOFILL S3 bucket name! You must enter the website endpoint, which you can find in S3 by looking in properties → Static Website Hosting. It should look like: http://BUCKETNAME.s3-website-REGION.amazonaws.com
Leave Origin Path blank, give a descriptive name for origin ID (Voices-Production)
Viewer Protocol Policy should be changed to redirect HTTP to HTTPS
Leave other settings standard until you see Compress Objects Automatically and set it to yes.
In Distribution Settings change Price Class to only use US, Canada, and Europe (the cheapest option)
For Alternate Domain Names, set the intended URL.
For SSL Certificate set it to Custom SSL Certificate click the text box, the imported certificate should be there. Select it.
Leave Custom SSL Client support at Clients that support Server Name Indication (SNI)
Set logging to on
For Bucket for Logs set Voices-Log
For prefix uses cloudfront-staging/production.
Set state to enabled, and select create distribution.
The now created distribution has a domain name (XXXYYYZZ.cloudfront.net)
Copy that and make a ticket for IT, and ask them to set a cname record that points the intended URL (step 9) to forward to the cloudfront domain name.
When IT has completed this you are done.
Final Steps
Log onto the newly built Voices server, run the build-voices.sh script as the ubuntu user.
Navigate to the new site and confirm it works.