AWS Amplify for a static website

Amplify is a recent addition to the line of services available on AWS. Its focus is on building what is known as “serverless” websites. While a bit of a misnomer because there are actually servers of some sort running behind the scenes, the maintenance and configuration of them is completely hidden from developers. You don’t have to designate servers, operating systems, VPCs (Virtual Private Clouds), etc.

Generally, serverless works with things like DynamoDB for data storage, API services for interaction with connected services, S3 for persistent file storage and lambda for any computation. All of that is available directly as you would expect on AWS, but it is also available through AWS Amplify which can take on almost all of the configuration and maintenance.

This website, however, is completely static and created using Hugo. It doesn’t need the majority of those services since it simply delivers web pages to your browser.

Amplify has two major components, one that lets you build and manage a serverless application, known as the Amplify API, the other is a thing called the Amplify Console.

Console takes on the role of managing your deployment process in much the same way as AWS Code Deploy and Code Pipeline, but without the complexity. That’s what were going to use for this site.

Code Commit

Amplify requires the use of some sort of git repository to manage your code. Most developers at this point should be very familiar with git tools and how to work with them. If this is still new to you, grab a copy of GitKraken and hook up a git hub repository to see how it works. You really need to have this in your toolbelt at this point.

To make things really easy, there is a branching pattern called git-flow (which is integrated in many tools including GitKraken). Implementing git-flow in your repository will prove to be extremely helpful in general and with Amplify things will just sort of “line up”.

When you implement git flow, you will have two parallel branches, “master” and “develop”. Additionally, you’ll work on feature branches most of the time which you will merge into the develop branch after you’re happy with the code. Finally, when you decide you are ready to go to production, you’re going to make a “release” which will merge the current develop branch into the master.

Why is this important?

Amplify Console is set up to read branches from your repository to build out your environments. For this website, we assign the master branch to our production environment and the develop branch to our staging/testing environment. We also assign a username/password combination to the development environment because we don’t want things we’re working on to be public until we push to production.

What does Amplify do?

Amplify is going to watch your branches and when it detects a change, it’s going to kick off your build and deploy your code.

So, when we complete a “release” in git flow, and push it to our remote repository (in this case, code commit), Amplify is going to see that and react.

The first thing it does is spin up a temporary docker container which it will use to build your app. Then it’s going to do a read-only checkout of the master branch to the temp environment. Next it’s going to run your build process.

When the build is complete, Amplify moves your new code to the hosting environment and finally it tears down the temporary build server.

Our build process

Lets take a look at our build file, amplify.yml:

version: 0.1
frontend:
  phases:
    preBuild:
      commands:
        - npm ci
    build:
      commands:
        - npm run build
        - hugo
  artifacts:
    baseDirectory: /public
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*

You’ll see that first we run a clean install from npm shown in the preBuild block. This will make amplify read your package-lock.json file (which you must add to your git repository). All of your dependencies will be added to the build server.

Next, we move to the “build” block and do our build script to create the optimized css and js for our site along with some static images. This is controlled by our webpack configuration.

Finally, now that the our static files have been created, we run hugo which assembles our site and dumps the results into the /public folder by default. You’ll want to make sure that you add the /public directory to your .gitignore file so it’s empty when amplify pulls your branch.

In the artifacts block, we tell Amplify that we only want to actually deploy the final site as it exists in the /public folder. We don’t need to publish all of our build assets. The files line tells amplify that we want all of the files in the baseDirectory to be included.

One last thing you’ll notice is that we cache node_modules on the build server to help speed the process, but with a simple site like this one, there really isn’t a noticeable difference if you leave it off.

After the build is completed, Amplify deploys the site.

Where did my files go?

If you’ve built a static site on AWS before, you would expect to see your site hosted as an S3 bucket. If you open the S3 service, however, you won’t find your site in there at all, so where did it go?

Amplify actually bypasses S3 completely and drops your site directly on Amazon’s CloudFront edge servers. Ok, so you should see a new distribution in CloudFront, right? Nope. Since the files get pushed to the edge servers directly, there is no entry in the CloudFront distributions. So how do I see my files for the site? As far as I can tell, you can’t. Because the ending environment is completely managed by AWS, there is no interface for us to look at.

The furthest upstream view we have of our files appears to be our source code repository. I’m not sure how I feel about that. I’m used to being able to see my files and review logs, but they simply aren’t available.

Verify

The last thing that happens as part of your build is that Amplify will look at your site in a few different mobile formats and take some screenshots. This is just a quick headless chrome view of your site so you can verify that your site’s home page renders as expected.

There really is a lot of magic that seems to be hidden away from us with Amplify. Since this is a new service, there might be some tools added later on that give us a little more vision into our app. Right now, the best way to know it’s working is by looking at the site like you’re doing right now.