jscom-blog

Welcome to the repository for My Homepage. A personal blog, written by a software engineer and lover-of-dogs currently living in Boise, Idaho. Writing about technology, software engineering, and my expanding family.

About

My website is built using Jekyll, a static site generator written in Ruby. The website is hosted on Amazon Web Services using Amazon S3 and Amazon CloudFront. All the AWS resources are provisioned using Terraform. The website is deployed using either a local script or via GitHub Actions.

The template for the jscom blog is jscom-ice and the Terraform modules used to provision the AWS resources are located in jscom-tf-modules

Repository Structure

Directory	Description
terraform	Contains Terraform scripts that provision all necessary AWS resources for the blog.
website	Contains the content for the blog.
.github	Contains GitHub Actions workflows that automate the deployment of the website.

Getting Started

Prerequisites

Ensure you have the following installed and configured:

• Jekyll & dependencies (Ruby): Install Ruby and then use Ruby's package manager to install Jekyll and Bundler. You can refer to the Jekyll Documentation for detailed instructions.

If you intend to apply terraform changes locally, you will also need the following:

• AWS CLI: Download and install the AWS CLI from the official AWS CLI website. After installation, run aws configure in your terminal and follow the prompts to input your AWS credentials.
• Terraform: Download the appropriate package for your system from the Terraform downloads page. Unzip the package and ensure that the terraform binary is available in your PATH.

Running Locally

1. Navigate to the website directory
2. Install the dependencies with bundle install (or bundle update if you already have the dependencies installed)
3. Run the website locally with bundle exec jekyll serve
4. Open your web browser and navigate to http://localhost:4000 to visit the website.

Deployment

GitHub Actions

Stage Deployment

• Triggered Manually
• Actions -> Deploy to STAGE -> Select Branch -> Run Workflow
• Targets https://stage.johnsosoka.com
• Workflow File: .github/workflows/deploy-stage.yml

Prod Deployment

• Triggered Automatically
• Merges to main Branch Trigger Deployment
• Targets https://johnsosoka.com & https://www.johnsosoka.com
• Workflow File: .github/workflows/deploy-prod.yml

AWS Website Infrastructure

Terrform is used to provision the AWS resources required to host the website. The infrastructure is defined in the terraform directory. It utilizes the static-website module from the jscom-tf-modules repository to provision most of the resources.

It sets up three CloudFront distributions for the "www", "root", "stage" subdomains, along with corresponding S3 buckets. The Terraform state is managed remotely using an S3 backend. Please note that some shared resources may be defined in the jscom-core-infrastructure repository.

Resources Provisioned

• CloudFront distributions for "www", "root", "media", and "stage" domains
• S3 buckets for the www, root, and staging websites
• IAM user with deployer access and permissions (Used for GitHub Actions CI/CD)
• Route53 records for mapping subdomains to CloudFront distributions

Refer to the Terraform configuration files for more details.

Usage

1. Install Terraform.
2. Set up your AWS credentials.
3. If Necessary, Modify the variables in variables.tf.
4. Run terraform init to initialize the backend and providers and fetch modules.
5. Run terraform plan to preview the infrastructure changes.
6. Run terraform apply to provision the AWS resources.

Notes

• This infrastructure uses CloudFront as a content delivery network and S3 buckets to host the website content.
• The IAM user created has permissions to manage the S3 buckets and create CloudFront invalidations. It is intended to be used by the GitHub Actions workflows.
• The Terraform state is managed remotely using an S3 backend.

Usage / Customizations

Image Carousel

I have written a carousel.html include that can be used to display a carousel of images. It expects an array of strings indicating image paths. You can easily configure images using the _data/carousels.yml file.

Add images to the yml file in the following format, name your collection i.e. baby-moon-mccall and then populate it with the image paths.

baby-moon-mccall:
  - /assets/img/slider/1/IMG_1061.jpeg
  - /assets/img/slider/1/IMG_1066.jpeg
  - /assets/img/slider/1/IMG_1075.jpeg

Wherever you'd like to display the carousel, add the following snippet:

{% assign carousel = site.data.carousels['baby-moon-mccall'] %}

{% include carousel.html images=carousel %}

Post Snippets

Posts may be published in multiple categories on this website, but I like to try and keep them somewhat organized. I created the posts.html include to fetch posts of a particular category & display them in a list.

Example Usage:

  {% raw %}
  {% include posts.html category="blog" post_display_limit=5 post_collection_title="Recent Blog Posts" %}
  {% endraw %}

This is currently used in the homepage as well as both the blog & notes landing pages.

Contributing

While this is a personal blog and I don't expect any contributions I do still welcome them. If you have a suggestion or would like to contribute a post, please either reach out to me directly or fork this repository and submit a pull request.

Todo

• Separate theme--place into separate repository install via gem
• create a terraform module for the website
• Migrate from Jekyll to Pelican??
• Modernize template/move to bootstrap
• Deployment Pipelines
  • Build Artifacts & Sync to prod S3 bucket upon merge to main
  • Rollback capability??
• Set up stage.johnsosoka.com
• Set up terraform s3 backend
  • S3 bucket for shared output variables & remote state management.
  • DynamoDB table to backend locking mechanism.
• Logging S3 bucket
  • configure website access logging
• Create independent files S3 bucket for keeping hosted download content separate from website content
  • create related cloudfront resources
  • create related dns entries (route53 resources)