Deploying Eleventy to a S3 bucket using AWS CodeBuild

It’s no secret that I love automation and making my job more efficient. Netlify has been a game changer for deploying web apps and static sites. However, Netlify isn’t an ideal solution for deploying static sites to sub-directories because by default it deploys to the root of a domain. Maybe it’s possible to change this behavior but I couldn’t find a way.

So I set out to see if I could set up an S3 bucket and deploy a static site (Eleventy) to a subdirectory within it. Turns out, I could and it was fairly straight-forward.

I’ll assume you already have an 11ty site ready to deploy and that you’ve signed up for AWS and understand what is free and what isn’t.

Create the bucket

Note: I’m essentially repeating the official AWS docs more concisely with screenshots, but for your reference, it may be helpful to check out the official documentation on using S3 as a website server.

From your S3 dashboard, click the “Create bucket” button to begin entering settings and configuration.

If you’re hooking up your own custom domain, name your bucket accordingly and create one for your subdomain (www) and one for the apex domain (no www). I’m not going deep into this part so refer to the official documentation on this.

Make sure you take note of the region that you set the bucket to be in. That will come into play later.

For static sites and web hosting on S3 buckets, uncheck “Block all public access” because for a website to work, you kinda need public access.

Within the Bucket Policy, you have to give it some rules to allow anonymous users to request the files. Paste the following from the AWS docs into the bucket policy:

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

Configuring CodeBuild

In short, CodeBuild takes a repository from CodeCommit, GitHub, or BitBucket and can automatically configure hooks so that when you push to the repository, it will trigger your build process. Let’s walk through the basic setup.

From the CodeBuild dashboard, when you click “Create build project” there are a few sections to fill out.

When you’re creating your new build project, ensure it’s in the same region as your S3 bucket that you created in the previous step.

Project configuration

Enter a project name that is kind of descriptive of what it’s going to do.

I used “ARBuild2019” because my CodeBuild is being used to build the college’s 2019 annual report website from Eleventy.

I left everything else blank.

Source

You can choose what the Source provider is (probably GitHub or BitBucket). If it’s a private repo you can connect via OAuth to get a list of all your repositories. This is the route I took.

Make sure that “Allow AWS CodeBuild to modify this service role…” is checked.

Under Primary source webhook events ensure that “Rebuild every time a code change is pushed to this repository” is checked. I left everything else as is.

If this option is not appearing, it’s because you are trying to use a public repository. You have to use a repository that your account has access to modify.

Environment

I wasn’t sure what to pick for the settings here but I tried this and it worked. I went with a Managed Image of Amazon Linux 2, with a standard runtime.

Again, make sure the box for “Allow AWS CodeBuild to modify this service role so it can be used with this build project” is checked and your Service role is populated. It was auto populated when I did it.

Buildspec

This is where the magic happens and this is where I got stuck for the longest. It’s not enough to use a single line command here, you need to edit the buildspec file to something like this:

version: 0.2

phases:
  install:
    commands:
      - npm install
  build:
    commands:
       - npx @11ty/eleventy --pathprefix=annual-report-2019
artifacts:
  files:
    - '**/*'
  base-directory: dist

Even though in the next section for “Artifact,” we will specify that we want the output to be uploaded to S3, without the ‘artifacts’ key being in the file, your build process won’t know what files to move over to S3.

So in the case of my eleventy project, I need to run npm install && npx @11ty/eleventy –pathprefix=annual-report-2019.

This eleventy configuration I have creates a dist folder in the root of the project, so dist needs to be set as the base-directory in the buildspec file. Some other versions of eleventy use _site or other file structures, whatever that is, enter it as the base-directory.

Then from there, I want to copy all files over, so I specify ‘**/*’ under files.

Artifacts

Finally, this part is pretty straightfoward.

Select Amazon S3 as the type, enter your bucket name that was created in the previous step.

I wanted it deployed to a sub-directory so I entered that under “Name”

And that’s it! Now you can trigger a build manually from the CodeBuild dashboard, or push to your repository to trigger it.

Next steps/further reading:

Leave a comment

What do you think?

%d bloggers like this: