CI/CD Implementation for Static Website Generator

Documentation - License - Author(s)

Documentation

This documentation assumes that you're running a UNIX machine (Linux or Mac) and you already have an AWS account. If you're running a Windows machine, the commands may be different.

Table of Contents

1. Intro
2. Demo
3. Installation
4. Diagnosis
5. Contribution

Intro

This is a demonstration of NDI Tech's CI/CD implementation for generated static websites. This website is built with Hugo. The deployment of the website is automated by AWS CodePipeline. The AWS infrastructure is provisioned by a terraform or an AWS CloudFormation template. You can use any other framework to build your website (React, Angular, etc.) and other infrastructure-as-code template (like AWS CloudFormation) to provision your infrastructure.

• The benefit of using a framework like Hugo is: your team can quickly create a static website with plenty of themes to choose from.

• Infrastructure as code:

  • If you deploy with Terraform: Terraform automates the process of setting up your AWS Codepipeline. Terrafrom works with other cloud providers, not just with AWS.
  • If you deploy with CloudFormation: CloudFormation will roll back if a stack cannot be created.
  • Each method has pros and cons. Pick the one that is most suitable for your need.

• AWS CodePipeline automates the workflow for developing, testing and deploying the website, in this case, to an S3 bucket. It works with any repository on GitHub (or the equivalent of your cloud provider), and any framework that crates a build or public folder contains all html, css and js files.

• Read more about how to manually set up an AWS CodePipeline and detailed explanation of a buildspec.yml file here.

Demo

• Working demo created by Terraform.
• Working demo created by CloudFormation.

Installation

Make sure you have on your machine:

• AWS CLI
• Hugo

Clone this repository to your local machine (using SSH):

$ git clone git@github.com:nditech/tech-staticsite-cicd.git
$ cd tech-staticsite-cicd

Deploy the stack with Terraform

Make sure you have on your machine:

• Terraform

Copy the output of the command below and use it as your webhook secret. You can use another command or just make your own secret from a string of random characters. It's recommended to to pull the webhook secret from the environment or something like SSM Parameter Store.

ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'

Create a secret.tfvars that looks like this:

github_repo = "<YOUR-REPO-NAME>"
github_token= "<YOUR-GITHUB-TOKEN>
webhook_secret = "<YOUR-WEBHOOK-SECRET>"

Then run these:

$ terraform init -input=false
$ terraform plan -var-file="secret.tfvars" -out=tfplan -input=false 
$ terraform apply -input=false tfplan

You should have your AWS infrastructure ready with a public website hosted in an S3 bucket.

Deploy the stack with AWS CloudFormation

• If you use AWS Console, just copy and paste the content of the .json file into CloudfFormation, remember to choose tab Template, validate the stack then create it. For more details, check AWS Documentation.
• If you use AWS CLI, run this command where the template file is:

  $ aws cloudformation create-stack --stack-name <STACK-NAME> --template-body file://pipeline.json --capabilities CAPABILITY_NAMED_IAM
  

• ⚠️ The template has default parameters' values, for your own use case, edit the template or use --parameter-overrides as described here.

Diagnosis

• Generate your GitHub token.
• Create and secure your GitHub webhook.
• Configure terraform file.
• Configure CloudFormation file.
• Configure a Hugo's template.
• Manually set up AWS CodePipeline.
• Error:

  Error: Error applying plan:
  1 error(s) occurred:
  * aws_codepipeline_webhook.codepipeline: 1 error(s) occurred:
  * aws_codepipeline_webhook.codepipeline: doesn't support update
  

  That means terraform webhook option doesn't support update, doesn't mean it did not deploy the infrastructure. Check your AWS CodePipeline to make sure your pipeline works.

Contribution

• Please read our Code Commits Guide and Documentation Guide.
• We also follow Google's Javascript Style Guide and Airbnb's React Style Guide.
• Do your own unit test before committing code.

License

GNU General Public License v3.0

Author(s)

Theme modified by Noble Ackerson from Elate theme which was ported to Hugo by Pieter Saey.

• Noble Ackerson

  nackerson@ndi.org  ·  LinkedIn

• Viet Nguyen

  vnguyen@ndi.org  ·  LinkedIn

⬆ back to top