Automating your Gatsby Deployments with AWS CodeBuild
In 2019 I set a goal for myself to take a dive into learning JavaScript. For much of my technology career I’ve worked in infrastructure, so the extent of my “programming” skills has been bash scripts, and whatever else we had at the time to automate our otherwise mundane tasks. More recently I have been using CloudFormation to deploy and manage my infrastructure within AWS, and Ansible for configuration management. While YAML (or JSON) are powerful in what they can do to define infrastructure and manifests for maintaining infrastructure configuration, I also don’t necessarily consider these full-fledged programming languages, they’re just not. In August of 2018, AWS announced their Cloud Development Kit (CDK), their latest infrastructure as code tool for building and managing cloud infrastructure using various programming languages (Python, TypeScript and JavaScript are GA as of this writing). For me, as someone with a career in infrastructure, it was a perfect tool to actually start learning a programming language (I chose JavaScript).
So, what does all this have to do with my article you might be asking? To be honest, nothing. Because as I started to work with the CDK, I also started to branch out into actually doing some actual development work on the side as well. Between A Cloud Guru, and freeCodeCamp I’ve taken several basic JavaScript courses to get a better understanding of what I’m working with. Then I decided that I would take on the responsibility of building and maintaining websites for two Masonic organizations that I’m a part of as a challenge to myself, but only having very basic skills I needed a framework to get started and learn with. Thankfully in the JavaScript community we have Gatsby, and that’s what I settled on.
For my site (soon to be sites plural) my hosting is set up as follows; S3, CloudFront and Route 53, all AWS products that allow me to host a static website very affordably. Now, the site I currently manage is simple enough that doing manual pushes from the command line on my development machine isn’t a problem. However, as someone who spends their time at work automating infrastructure and software deployments where would the fun be in doing things “the old-fashioned way”? For this exercise on top of the three AWS services mentioned above, we’ll be adding GitHub and AWS CodeBuild to automate deployments for us.
Gatsby is a React based framework that allows developers to build “blazing fast websites and apps”. The power of Gatsby comes in its ability to pull from multiple data sources; Content Management Systems such as Contentful, Drupal, WordPress, etc., Markdown, or other data sources such as API’s, databases and more. Its flexibility becomes more apparent as you get into hosting as its quite simple to host a Gatsby site in any of the popular hosting providers available to developers. While the vast majority of sites created with Gatsby are static, the framework itself is flexible enough to allow a developer to add dynamic feature to their site as well. Couple all this with a great library of starter templates and I hope you can begin to see why I decided to start developing with Gatsby.
For the purpose of this article, I’m going to assume you already have a Gatsby project created, and you’re now at the point where you’re looking deploy your code to your selected hosting provider. In our case here, I will be using a simple one-page site hosted using the above AWS products I mentioned above. In addition to the hosting, we’re going to be using GitHub to host our code, AWS CodeBuild to build and test our code (although in my case I haven’t built any tests yet) and a Gatsby plugin called gatsby-plugin-s3 that will enable us to deploy our code to our S3 bucket. To start out, we’re going to add the gatsby-plugin-s3 to our code base. Make sure you’re in your project directory, then run the following command;
$ npm i gatsby-plugin-s3Next, we want to add the plugin to our gatsby-config.js file, and configure it to point at our S3 bucket that will host our project;
Next, we want to configure a deployment script within our package.json file. Open that script in your editor of choice, find the scripts section and add the following line;
You will notice in the official documentation there is an option to add a –yes to that line to skip the confirmation prompt. Since we are using a Continuous Integration (CI) environment to deploy our code we do not need that flag.
With that complete, let’s configure CodeBuild to build, test and push our code to our S3 bucket. The first section to configure is our Project configuration. The only section required is a project name, so ensure that is filled out with your project name, and go on if you like. Personally, I like giving a description, everybody should enable build badges to spruce up their project README and I highly suggest adding tags to your project under the ‘Additional configuration section’. Depending on how you manage your AWS account(s), tagging, when utilized properly can be a life saver in determining where your AWS costs are coming from.
Next, we’ll configure the Source section. Make the following selections under this section;
1. Select GitHub as your Source provider
2. On the repository line check the ‘Repository in my GitHub account’ option
3. Add your repository URL to the GitHub repository section (you may have to log in to GitHub first)
4. Select a pull request, branch, commit ID, etc. you want to use as your source version
5. Leave the Git clone depth set to the default of 1
In the Primary source webhook events section check the box next to ‘Rebuild every time a code change is pushed to this repository’, and then select ‘PUSH’ as your Event type.
Next, we’re going to configure our environment for CodeBuild;
1. Leave the default of ‘Managed image’ selected
2. Select your operating system of choice (I selected Ubuntu because my development environment is Ubuntu based)
3. Leave the default ‘Standard’ Runtime selected
4. Leave the default of ‘aws/codebuild/standard:1.0’ selected for Image
5. Leave the default of ‘Always use the latest image for this runtime version’ selected for version
6. Leave the default of ‘Linux’ selected for Environment type
7. Create a new service role.
Under the Buildspec section keep the default of ‘Use a buildspec file’ selected. We will revisit the buildspec file below once we’ve finished configuring our CodeBuild job.
For artifacts we’re going to select the ‘No artifacts’ section. This is because we are using the gatsby-plugin-s3 plugin to push our code to our source Bucket. If you ever decided to not use the plugin, you could select Amazon S3, and configure that section as your project would dictate.
Finally, leave the ‘CloudWatch logs — optional’ button checked in the Logs section, and with that we’re done configuring our project. You can click the ‘Create build project’ button and we’re ready to move on to the next step.
So now you have a CodeBuild job set up for your project! The next item we need to make this work, is our buildspec.yml file we mentioned above. Your buildspec.yml file is the file that will tell CodeBuild what commands and settings to use as it runs a build of your project. The file is simply called buildspec.yml, and you store it in the project root of your source directory. Let’s create one right now;
Quite simply, what we have is our work broken down into various phases; we install Gatsby, install our dependencies defined in our package.json file, we build our project, and finally we deploy it. If we had tests as a part of our project, we would simply add another phase that ran those tests. In our artifacts section we’re defining where our project code is stored, and what should be deployed to our S3 bucket. In this case, our built project is stored in the ‘project’ directory, and the **/* is telling CodeBuild to deploy all files in that directory recursively. The discard-paths option shortens the path in the build output artifact. If, for example we had a file called /com/mycompany/app/HelloWorld.java, by specifying yes in our buildspec, that file would simply become HelloWorld.java. For more information on Buildspec files, and all the options you can read the following documentation.
Commit your new buildspec file, and push your updated repository and if everything is configured correctly, you should see your job running from the AWS CodeBuild console if you go to it. If not, double check all your job configurations and make sure they’re correct.
Congratulations, you just configured your project up automatically update on every push to your GitHub repository! While this tutorial only walks you through one hosting model, and one deployment model, do know that Gatsby can be hosted and deployed by all the popular tools and services, not just AWS. I do hope that you walk away from this with a firm understanding of how you can configure an automated deployment solution for your Gatsby site. Go forth and do great things!
