DEV Community: Rebeca Murillo

CI/CI deploy a static website to AWS S3 bucket through Github Actions

Rebeca Murillo — Fri, 22 Dec 2023 10:00:38 +0000

Introduction

Welcome to this tutorial where we'll delve into the process of setting up continuous integration and continuous delivery (CI/CD) for deploying a static website to an Amazon S3 bucket directly from your GitHub repository. We'll walk through the process of setting up GitHub Actions in your project, configuring your AWS account, and ensuring that your website is running smoothly after each deployment.

This configuration might take some time to setup, but it will help you save time afterwards ! Your website will be updated automatically with one click, just by running the Github workflow on your main branch.

This tutorial breaks down in three steps :

Github Actions workflow
Setub AWS Role to connect with Github Actions
Setup Github Actions secrets and run the workflow

Requirements

To follow along this tutorial, you will need to setup in advance the following :

A GitHub repository with your static website source code. Check my tutorial on starting a multilingual i18n blog with Astro.
A AWS account with an S3 bucket hosting your static website. You can learn this with my tutorial on hosting a static website in AWS S3 bucket
A CloudFront distribution for the cache and CDN.

Through this guide, you'll gain an in-depth understanding of building, quality checking, and deploying your static website, and finally checking the production site. Let's get started on this exciting journey of automating your website deployment!

Github Actions workflow

To kickstart the process, we'll set up GitHub Actions in the project.

Add a file under .github/workflows/build-deploy.yml in your project directory.
Copy the following content, adapt according to your needs.

name: Build and deploy to S3 bucket

on: workflow_dispatch

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 18
      - name: Install Dependencies
        run: npm install
      - name: Build and Output to Dist
        run: npm run build
      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: build-artifacts
          path: dist

  quality:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
      - name: Download Build Artifacts
        uses: actions/download-artifact@v3
        with:
          name: build-artifacts
          path: dist
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"
      - name: Run localhost server
        run: |
          cd dist ; ls -la ;
          python -m http.server 8080 &
      - name: Wait for Local Server to Start
        run: sleep 3
      - name: Check homepage status in localhost
        run: |
          URLs=("http://localhost:8080/" "http://localhost:8080/en/" "http://localhost:8080/es/" "http://localhost:8080/fr/")
          for url in "${URLs[@]}"; do
              response_code=$(curl -w "%{http_code}" -I "$url" -o /dev/null)
              echo -e "e HTTP Status Code for $url: $response_code"
              echo "HTTP Status Code for $url: $response_code"

              if [ "$response_code" -ne 200 ]; then
                  echo -e "::error::Error: Unexpected status code for $url"
                  exit 1
              fi
          done

  aws_deploy:
    runs-on: ubuntu-latest
    needs: [build, quality]
    steps:
      - name: Download Build Artifacts
        uses: actions/download-artifact@v3
        with:
          name: build-artifacts
          path: dist
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ${{ secrets.AWS_REGION }}
      - name: Empty S3 Bucket
        run: aws s3 rm s3://${{ secrets.AWS_S3_BUCKET }} --recursive
      - name: Upload to S3 bucket
        run: |
          ls -la dist/
          aws s3 cp dist/. s3://${{ secrets.AWS_S3_BUCKET }} --recursive
      - name: Clean CloudFront Cache
        run: aws cloudfront create-invalidation --distribution-id ${{ secrets.AWS_CLOUDFRONT_DISTRIBUTION_ID }} --paths "/*"

  healthcheck:
    runs-on: ubuntu-latest
    needs: aws_deploy
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
      - name: Check homepage status @ https://mywebsite
        run: |
          URLs=("https://rebeca.murillo.link/" "https://rebeca.murillo.link/en/" "https://rebeca.murillo.link/es/" "https://rebeca.murillo.link/fr/")
          for url in "${URLs[@]}"; do
              response_code=$(curl -w "%{http_code}" -I "$url" -o /dev/null)
              echo -e "e HTTP Status Code for $url: $response_code"
              echo "HTTP Status Code for $url: $response_code"

              if [ "$response_code" -ne 200 ]; then
                  echo -e "::error::Error: Unexpected status code for $url"
                  exit 1
              fi
          done

The workflow can be triggered by a manual run or you can customize it to run on conditions like a branch push on the main branch. Refer to Github Actions Events that trigger workflows documentation

The workflow is partitioned into four different jobs:

Build
Quality check on localhost
S3 bucket deployment
Checking the production site

Let's go in detail into each job.

Note that the permissions is mandatory for aws-actions/configure-aws-credentials to authenticate !
permissions:
 id-token: write
 contents: read

1. Build Job

The first step is to build the static website source, following your website configuration and framework. In this tutorial, the project is built with the Astro Framework, so we run run a script to install Node dependencies with Node.js and then build the source code.

Setup environment with Nodejs and install dependencies with npm install, with Github Actions setup Node
Build the static website final sources with command npm run build, by default Astro framework saves the built sources in the dist/ folder.
The content of the build destination folder folder needs is saved and transferred to the following jobs in the workflow. We do this with the Github actions actions/upload-artifact

The subsequent jobs will be running the Github Actions Download Artifact, in order to retrieve the dist/ folder content.

2. Quality Check on localhost

In this step you can add your project's test command, if you have one. Like for example npm run tests

The second job involves running a quality check. For our static website example, the quality check consists on hosting the website locally and calling the homepage, or any other important pages.

The source files from the dist/ folder from our first job are used, retrieved with Github Actions Download Artifact
Run a local host with the static website content with Python setup Github Actions
Check some of the website pages are functioning as expected. If any of the pages are not responding properly (200 status), the exit 1 is triggered, causing the GitHub workflow to fail. This will prevent the deployment of the source code in our S3 bucket.

3. S3 Bucket Deployment

After checking that the source generated code is running correctly, the third job will be deploying the source code to the AWS S3 bucket.

The source files from the dist/ folder from our first job are used, retrieved with Github Actions Download Artifact
The AWS configure-aws-credentials Github Action allows the connection to the AWS S3 bucket through an AWS Role. The configuration of this role is explained in the next chapter
The AWS bucket hosting the static website is updated by first deleting the old content, and then uploading the updated source files.
Finally the CloudFront cache is cleaned, as it may not immediately reflect the website changes.

4. Checking the Production Site

The final job repeats the quality check from the second job, but this time, on the final website URL. I've set it up to check four pages, the homepage in three different languages, to ensure that the site is up and running after deployment.

In the next section, we will look into AWS configurations necessary for this CI/CD setup.

Setub AWS Role to connect with Github Actions

Moving on, we are now going to set up our AWS account to connect it with GitHub Actions. To accomplish this, we need to create a role in AWS. This role will be used to configure the credentials in the GitHub Actions workflow.

Refer to the AWS documentation for more details about this process : Use IAM roles to connect GitHub Actions to actions in AWS

1. Create an OIDC provider for Github

To start off, we need to create an identity provider for GitHub.

In the AWS Console, go to Identity and Access Management (IAM), under Access Management > Identity Providers
Click on 'Add a new provider' :
- provider type : 'Open ID Connect Provider'
- provider URL :token.actions.githubusercontent.com
- Audience : sts.amazonaws.com.

Once we have our identity provider established, we can proceed to create the role.

2. Create the AWS Role

In the AWS Console, go to Identity and Access Management (IAM), under Access Management > 'Roles'
Click to create a "New role" :
- Entity type: Web identity.
- Select the identity provider we created in the previous step. The audience will be the default one.
- The GitHub organization is essentially your GitHub account where the project is hosted.
- The name of your GitHub repository
- The branch in your Github repository that will be allowed to run the Github Actions workflow
In the Permissions Policies step, setup the rules according to the actions that will be executed by the Github Actions workflow. For this tutorial, the permissions required are :
- AWS S3 bucket management: to delete and upload content in the bucket
- AWS Cloudfront management: to reset the CDN cache
Save the new role

In the trust policy, you can verify important information regarding your Github repository permissions and the concerned branch. You can adapt this to your use case.
Upon creating the role, open it to copy the ARN (Amazon Resource Name), which is needed in the next step for setting up the secrets in GitHub.

Setup Github Actions secrets and run the workflow

Back in your GitHub project, set up the required secrets for the workflow.

Go to your GitHub project settings,
Then to 'Secrets and Variables' under 'Actions'
Finally create a secret for each variable with 'Create a new repository secret'. In this tutorial, the secrets used in the workflow include:
- AWS_ROLE_ARN: the ARN from the AWS role created in the previous step
- AWS_REGION: the AWS region for the bucket
- AWS_S3_BUCKET: AWS S3 bucket name
- AWS_CLOUDFRONT_DISTRIBUTION_ID: the AWS CloudFront distribution ID

With all these configurations in place, your AWS account is now set up and ready to be connected with your GitHub Actions.

To run the workflow, navigate to the 'Actions' tab in the GitHub repository, select the workflow and run it from the corresponding branch.

Once the workflow has started, you can monitor its progress. It will sequentially execute the four jobs we outlined earlier: build, quality check on localhost, S3 bucket deployment, and checking the production site.

Note that choosing the wrong branch will result the workflow to return errors. The branch must be allowed in the AWS role policies.

I hope this tutorial gives you a clear understanding of how the AWS role and GitHub Actions work together to ensure secure and controlled deployments of your website. The process is now fully automated, and the permissions are set up to prevent unauthorized deployments, ensuring that your website remains secure and updated with only one click !

Host a static website in AWS S3 bucket through Cloudfront CDN

Rebeca Murillo — Thu, 16 Nov 2023 18:09:23 +0000

Introduction

In today's digital era, having a well-structured, functional website is a must for any business or individual seeking to maintain an online presence. In this blog, we'll walk you through the process of hosting a static website on an Amazon S3 bucket, and using CloudFront for the Content Delivery Network (CDN). Let's get started.

This guide assumes you have a basic understanding of AWS and have the source code for your website ready to go.

We'll be building the source code with Astro framework.

Why did I choose to host my website on an S3 bucket ?
Because this is a flexible and low maintenance solution, compared to hosting on a server. Once the setup is done, the website update requires only a folder upload to a bucket. Also is it a very low cost solution, depending on the number of visits, starting at a few cents par month in my case, for a personal website with very low traffic.

Step by step guide

The requirements for this guide :

the source code for a static website

an AWS account

a DNS hosted in Route 53 (or the provider of your choise), domain name as your.website.url in this tutorial

bucket name as my-bucket-name in this tutorial

1. Preparing your website source code

First of all, we will need the sources for our static website, built by the framework of your choise, or in plain HTML/JS/CSS if you prefer.

In my case, I'm developing my website with Astro framework with static site feature.

npm install
npm run build

This command line installs all required Nodejs dependencies, and builds the final source code for the static website.
By default the sources are generated in the folder dist/. This content will be uploaded to our S3 bucket in order to host as a website.

Is is important to have the following pages in the root of your website.

/index.html, the homepage for your website
/error.html, the default error page, in the following example I also have a 404.html page, for 404 not found error redirections.

2. Configuring a Static Website on Amazon S3

Once the source code for the website is prepared and the final sources are built, the next step is creating a bucket on Amazon S3 and uploading the prepared source files. This process involves setting up the S3 bucket, enabling the static website hosting, adjusting permissions, and setting up error redirection.

Setting Up the S3 Bucket

Navigate to Amazon S3's Bucket Management and create a new bucket :

Bucket name : my-bucket-name
AWS region of your choise
Uncheck option "Block all public access", this sets the bucket as public.
Make sure to acknowledge the security settings and keep the default configurations.
Once the bucket is created, upload the source files from step 1

Check out AWS S3 bucket naming best practices

Enabling Static Website Hosting

Next, enable the static website hosting in the bucket properties.

Go to your bucket, then under tab Properties
Edit the Static website hosting and enable
Hosting type : "Host a static website"
Index document : index.html (or the name of your homepage in the source files)
Error document : error.html (or your specific error page in the source files)

Save the changes made.

You will find the static website URL for your bucket under the Properties tab, section Static website hosting

Find more usefull information in the AWS documentation S3 : Enabling website hosting

Adjusting Permissions

At this stage, when you navigate to the website URL, you may encounter an error 403 Forbidden with code : AccessDenied.
We will resolve this issue by adjusting the permissions in the bucket edition.

Go to your bucket, then under Permissions tab
Scroll to Bucket Policy and edit
Paste the following policy and set up your bucket as the resource (replace my-bucket-name with your bucket name)
Finally save the changes.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::my-bucket-name/*"
        }
    ]
}

Refer to the AWS documentation S3 : Setting permissions for website access

Setting Up Error Redirection (optional)

To provide a better user experience, you can set up automatic redirection to a custom page for non-existing pages (404 error). This process involves setting up redirection rules in the static website hosting configuration of your bucket.

Go to your bucket then under tab Properties
Edit the Static website hosting configuration
Paste the following redirection rule, adapt according to your setup (replace my-bucket-name.s3-website.eu-west-3.amazonaws.com with your S3 bucket website host)

[
    {
        "Condition": {
            "HttpErrorCodeReturnedEquals": "404"
        },
        "Redirect": {
            "HostName": "my-bucket-name.s3-website.eu-west-3.amazonaws.com",
            "ReplaceKeyWith": "404.html"
        }
    }
]

This step is optional. Checkout the possible redirections rules in the AWS documentation S3: Configuring a webpage redirect

3. Configuring SSL Certificate and CDN

After setting up the static website on Amazon S3, the next step is securing your domain with an SSL certificate and setting up a Content Delivery Network (CDN) using Amazon CloudFront.

Requesting an SSL Certificate

Navigate to the Certificate Manager and request a new certificate for your domain.

Remember that the certificate must be in the us-east-1 region, this is a Cloudfront requirement for now (november 2023)
Request a public certificate
Domain name : your.website.url
Choose the validation method that better suits you (DNS or email)
Once the certificate is requested, the status is in "Pending validation"

Follow the instructions for the validation process according to the chosen method, by email or DNS

Validating certificate through Route 53

If your DNS is not hosted in AWS Route 53, refer to the documentation of your DNS provider. You will need the CNAME name and value in the SSL certificate page

Go to Route 53 under your DNS
create a new record type CNAME
copy the name and value from SSL certificate in the previous step

The validation process may take a few minutes to complete.

4. Setting up CDN and DNS for your website

Now that we have our website running in our S3 bucket and that we have a SSL certificate for our custom DNS, we can complete the Cloudfront CDN setup and finally configure the website domain name. The domain name will redirect to the Cloudfront distribution.

Create your Cloudfront distribution

Navigate to CloudFront and create a new distribution
In the origin domain, paste your S3 bucket website host : my-bucket-name.s3-website.eu-west-3.amazonaws.com (replace with your S3 bucket website host)
Choose request redirects from HTTP to HTTPS
Choose the certificate that you've just validated
Add an alternate domain, pointing to your DNS your.website.url

If you do not see the certificate, it might be one of the following :

try to refresh the page, or the refesh button next to the certificate selection

is the SSL certificate valid ?

is the SSL certificate in the correct region required by Cloudfront (us-east-1 as of november 2023)

Setting up domain name to Cloudfront distribution

If your DNS is not hosted in AWS Route 53, refer to the documentation of your DNS provider. You will redirect your custom domain name to the Cloudfront distribution domain name found under the Cloudfront distribution and General tab. The domain name looks like the following : <dsitribution ID>.cloudfront.net

Route 53

The last step is setting up your domain to point to the Cloudfront distribution.

Go to in Route 53
Create an new record
Name is your custom domain your.website.url
Select Alias, and choose Alias to CloudFront distribution.
Choose your created distribution

After a few minutes, your website will be available through your custom domain with the proper SSL certificate.

Other DNS providers

Go to your DNS provider
Create an new A record
Name is your custom domain your.website.url
Value is the CDN distribution host : <dsitribution ID>.cloudfront.net

Conclusion

In conclusion, hosting a static website on Amazon S3 is a practical, low cost and efficient method for maintaining an online presence. The process involves building the website's source code, configuring the static website on Amazon S3, securing the domain with an SSL certificate, and setting up a CDN with Amazon CloudFront.

This guide covered each of these steps in detail, from setting up the S3 bucket and enabling static website hosting, to adjusting permissions and setting up error redirection. Additionally, it touched on the steps to secure your domain, request an SSL certificate, and set up a CDN. Lastly, it highlighted the importance of finalizing DNS setup to ensure your website is available with the appropriate SSL certificate.

By following these guidelines you can create, host, and manage their static websites in a secure and reliable environment. This not only ensures a seamless user experience but also leverages the power and flexibility of Amazon's web services ecosystem.

Astro Starter Template : Blog enhanced with I18n

Rebeca Murillo — Sun, 12 Nov 2023 07:25:17 +0000

Intro

Welcome to this hands-on tutorial where we'll delve into the Astro Blog Starter i18n template, featuring i18n capabilities with translations in multiple languages. Just to clarify, we're working with a template project here, meaning you can spawn your own repository right from it. Our template of choice is derived from Astro's official Starter Kit, thus carrying its robust DNA.
Before we get started, I recommend a basic understanding of Node.js and Astro to make the most of this journey. Let's dive in!

Create a new Github repository from template

To start, let's create a new repository from the Astro Blog Starter i18n template. You new repository will have the core features of the Astro Starter Blog template with the added features of i18n with translations in multiple languages.

Define your languages

To configure your languages, you will need to configure the available languages, and start a translations object with languages properties.

Setup available languages and default language in the file src/i18n/utils.ts. This is important for the header configuration and canonical URL for SEO. File src/i18n/utils.ts

export const LANGUAGES = {
  en: "English",
  fr: "Français",
  es: "Español",
};

export const DEFAULT_LANG = "en";

...

Initiate your translations keys in src/i18n/ui.ts File src/i18n/ui.ts

export const ui = {
    en: {
        "site.title": "Astro Blog"
    },
    fr: {
        "site.title": "Astro Blog"
    },
    es: {
        "site.title": "Astro Blog"
    }
}

Create a new blog post in English, Spanish and French languages

Let's now add a new blog post, with translations.

In the src/content/blog folder, create a new folder and call it "new-blog", this will be the slug for the blog pages.
Then, inside folder src/content/blog/new-blog, create a new file for each language, in my case English en.md, Spanish es.md, and French fr.md.
In each file copy the data required in the collection. Refer to the src/content/config file for collection setup, if you would like to add any more data usefull to your blog posts.

Example of file src/content/blog/new-blog/es.md content.

---
title: 'Mi primer blog'
description: 'Lorem ipsum dolor sit amet'
pubDate: 'Jul 08 2022'
heroImage: '/blog-placeholder-3.jpg'
author: 'Me'
lang: 'es'
---
# Mi primer Blog ! 
Lorem ipsum dolor sit amet, consectetur adipiscing elit...

After adding the content for each language, we can navigate to the blog section on the site to see our new blog post in each language. If the translations are appearing correctly, we have successfully added a new blog post.

Create a new static page in English, Spanish and French languages

Now, let's add a new static page with translations.

In src/pages/[lang] create a new file new-page.astro.
In src/i18n/ui.ts add a translation key for each language in the corresponding property for en, es, fr.

File src/i18n/ui.ts

export const ui = {
    en: {
        "site.title": "Astro Blog",
        "newpage.title": "New page title",
        "newpage.description": "New page description"
    },
    fr: {
        "site.title": "Astro Blog",
        "newpage.title": "Nouvelle page",
        "newpage.title": "Nouvelle page description"
    },
    es: {
        "site.title": "Astro Blog",
        "newpage.title": "Nueva pagina",
        "newpage.title": "Nueva pagina description"
    }
}

Copy the Layout configuration from the index.astro for example. And set your translations keys using the function

File src/pages/[lang]/new-page.astro

---
import Layout from "../../layouts/Layout.astro";

import { getLangFromUrl, useTranslations } from "../../i18n/utils";

const lang = getLangFromUrl(Astro.url);
const t = useTranslations(lang);

export async function getStaticPaths() {
  return ["en", "fr", "es"].map((lang) => {
    return { params: { lang } };
  });
}
---

<Layout title={t("newpage.title")} description={t("newpage.description")} lang={lang}>
  <h1>{t("newpage.title")}</h1>
</Layout>

Check your new page in your browser http://localhost:4321/en/new-page, http://localhost:4321/fr/new-page, and http://localhost:4321/es/new-page

And that's it! You have now added a new blog post and a new static page to your Astro blog project in multiple languages.

Optimization for SEO

This Astro Starter Blog I18n Template is pre-optimized for SEO. This is a critical aspect of any online project as it enhances visibility and discoverability on search engines.

One of the ways this optimization is achieved is through the use of canonical URLs. In the template, the default language is set to English. This means all canonical URLs will default to the English language versions.

On the other hand, alternate URLs are defined accordingly to each language. For instance, in the Spanish version, the alternate languages (which are English and French in this case) will appear in the head block. This setup ensures that search engines accurately index all versions of the site, preventing duplication and enhancing SEO performance.

In addition, the Astro sitemaps plugin, already installed in this project, automatically generates sitemaps. These sitemaps include all versions of the website in all languages, providing further assistance to search engines for indexing the website.

Conclusion

The Astro Starter Blog I18n template comes with the base features for a static website, blog pages in Markdown, translations in multiple languages with i18n feature, SEO optimization, ensuring that your content is ready to reach an international audience right from the get-go.