https://github.com/byu-oit/hw-static-site
Template for creating a product specific repo with terraform files for deployment
https://github.com/byu-oit/hw-static-site
devops template
Last synced: 5 months ago
JSON representation
Template for creating a product specific repo with terraform files for deployment
- Host: GitHub
- URL: https://github.com/byu-oit/hw-static-site
- Owner: byu-oit
- License: apache-2.0
- Created: 2020-06-10T22:23:11.000Z (about 6 years ago)
- Default Branch: prd
- Last Pushed: 2025-09-05T02:13:25.000Z (10 months ago)
- Last Synced: 2025-09-05T04:11:18.226Z (10 months ago)
- Topics: devops, template
- Language: HCL
- Homepage:
- Size: 296 KB
- Stars: 0
- Watchers: 21
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# hw-static-site
Example of creating and deploying a Static Website with S3 and Terraform on AWS.
## Prerequisites
* Install [Terraform](https://www.terraform.io/downloads.html)
* Ensure your account has a [Terraform State S3 Backend](https://github.com/byu-oit/terraform-aws-backend-s3) deployed.
## Setup
* Create a new repo [using this template](https://github.com/byu-oit/hw-static-site/generate).
You need your own repo so that you can push changes and have GitHub Actions deploy them.
Keep your repo name relatively short. Since we're creating AWS resources based off the name, we've seen [issues with repo names longer than about 24 characters](https://github.com/byu-oit/hello-world-api/issues/22).
* Clone your new repo
```
git clone https://github.com/byu-oit/my-new-repo
```
* Check out the `dev` branch
```
cd my-new-repo
git checkout -b dev
```
* Find and replace across the repo:
* replace `977306314792` with your dev AWS account number
* replace `539738229445` with your prd AWS account number
* replace `hw-static-site` with the name of your repo
* replace `byu-oit-terraform-dev` with the name of your `dev` AWS account
* replace `byu-oit-terraform-prd` with the name of your `prd` AWS account
* Commit/push your changes
```
git commit -am "update template with repo specific details"
git push
```
## Deployment
### Deploy the "one time setup" resources
```
cd terraform-iac/dev/setup/
terraform init
terraform apply
```
The output from this will give you the NS records for your new Hosted Zone. These NS records need to be entered into the DNS system of record for the parent domain.
For example, if your site's URL was `mysite-dev.byu.edu`, you would need to add the following records to QIP (as QIP is the DNS system of record for `byu.edu`):
```
mysite-dev.byu.edu NS ns-1486.awsdns-57.org
mysite-dev.byu.edu NS ns-1853.awsdns-39.co.uk
mysite-dev.byu.edu NS ns-829.awsdns-39.net
mysite-dev.byu.edu NS ns-91.awsdns-11.com
```
(You'll need to change the actual values based on the output from `terraform apply`)
As another example, if your site's URL was `mysite-dev.mydepartment.byu.edu`, and `mydepartment.byu.edu` was already controlled by a Route 53 Hosted Zone, you would manually add the NS records to the Hosted Zone for `mydepartment.byu.edu`.
In the AWS Console, see if you can find the resources from `setup.tf` (Route 53 Hosted Zone, IAM Role).
### View the workflow run
If you look at `.github/workflows/deploy.yml`, you'll see that it is setup to run on pushes to the dev branch. Because you have already pushed to the dev branch, this workflow should be running now.
* In GitHub, in the Actions tab, click on the workflow run (it has the same name as the last commit message you pushed)
* Click on the `Build and deploy Webapp to S3` job
* Expand any of the steps to see what they are doing
### View the deployed application
Anytime after the `Terraform Apply` step succeeds :
```
cd ../app/
terraform init
terraform output
```
This will output a DNS Name. Enter this in a browser. It will probably return an error. This is because your content hasn't been uploaded yet, or the CloudFront distribution hasn't been updated.
Wait for the `Invalidate CloudFront cache` step to succeed, then try again.
In the AWS Console, see if you can find the other resources from `main.tf` (S3 Bucket, CloudFront Distribution).
### Push a change to your application
Make a small change to `index.html`. Commit and push this change to the `dev` branch.
```
git commit -am "try deploying a change"
git push
```
In GitHub Actions, watch the deploy steps run (you have a new push, so you'll have to go back and select the new workflow run instance and the job again). Once the `Invalidate CloudFront cache` step succeeds, hit your application in the browser and see if your change worked. If you aren't seeing the change, you may need to invalidate your browser cache as well.
> Note:
>
> It's always best to test your changes locally before pushing to GitHub and AWS. Testing locally will significantly increase your productivity as you won't be constantly waiting for GitHub Actions and CodeDeploy to deploy, just to discover bugs.
>
> You can either test locally inside Docker, or by pointing your browser directly at your local files.
## Learn what was built
By digging through the `.tf` files, you'll see what resources are being created. You should spend some time searching through the AWS Console for each of these resources. The goal is to start making connections between the Terraform syntax and the actual AWS resources that are created.
Several OIT created Terraform modules are used. You can look these modules up in our GitHub Organization. There you can see what resources each of these modules creates. You can look those up in the AWS Console too.
### Related Modules
* [Terraform AWS Domain Redirect](https://github.com/byu-oit/terraform-aws-domain-redirect)