Deploy a Hugo Site to S3 with CodeBuild

Hugo is one of the fastest static site generators available, and combined with AWS CodeBuild and S3, you get a fully automated deployment pipeline with minimal infrastructure overhead. This guide walks through setting up a Hugo site, configuring CodeBuild, and deploying to S3.

Prerequisites

• An active AWS account with permissions for S3, ECR, and CodeBuild
• Hugo installed locally (installation guide)
• AWS CLI configured with valid credentials
• Git installed and a remote repository (GitHub, Bitbucket, or CodeCommit)

Create a Hugo Site

Start by scaffolding a new Hugo project and adding a theme:

hugo new site my-site
cd my-site
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
echo 'theme = "ananke"' >> config.toml

Create your first post and verify the site builds locally:

hugo new posts/my-first-post.md
hugo server -D

Once you’re satisfied with the local preview, commit your changes:

git add .
git commit -m "Initial Hugo site setup"

Configure S3 Deployment

In your config.toml, set the baseURL to your S3-hosted domain or bucket URL:

baseURL = 'https://your-domain.com/'

Hugo has built-in deployment support. Add the deployment target to config.toml:

[deployment]
[[deployment.targets]]
name = "s3"
URL = "s3://your-bucket-name?region=us-east-1"

You can also sync manually using the AWS CLI:

hugo && aws s3 sync public/ s3://your-bucket-name --delete

Create the buildspec.yaml

The buildspec.yaml file tells CodeBuild how to build and deploy your Hugo site. Place it in the root of your repository:

version: 0.2

env:
  variables:
    HUGO_VERSION: "0.123.0"

phases:
  install:
    commands:
      - wget -q "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.deb"
      - dpkg -i "hugo_extended_${HUGO_VERSION}_Linux-64bit.deb"
  pre_build:
    commands:
      - echo "Hugo version:" && hugo version
  build:
    commands:
      - hugo --minify
  post_build:
    commands:
      - aws s3 sync public/ s3://${S3_BUCKET} --delete
      - echo "Build completed on $(date)"

artifacts:
  files:
    - '**/*'
  base-directory: public

Update HUGO_VERSION to match the version you need. Use hugo_extended if your theme requires SCSS/SASS processing.

Set Up CodeBuild

1. Create a CodeBuild project in the AWS Console (docs).
2. Source: Connect your Git repository (GitHub, Bitbucket, or CodeCommit).
3. Environment: Use a managed image (Amazon Linux 2, standard runtime) or a custom Docker image from ECR if you need specific tooling.
4. Service role: Ensure the CodeBuild service role has s3:PutObject, s3:DeleteObject, and s3:ListBucket permissions on your target bucket.
5. Environment variables: Add S3_BUCKET with your bucket name.

Monitoring and Troubleshooting

CloudWatch Logs: CodeBuild streams build logs to CloudWatch automatically. Check these first when a build fails.

Common issues:

• Hugo version mismatch: Ensure the version in buildspec.yaml matches what your theme requires.
• Permission denied on S3: Verify the CodeBuild service role has the correct S3 permissions.
• Theme not found: If using Git submodules, ensure CodeBuild clones submodules by enabling “Git clone depth” and “Fetch Git submodules” in the source configuration.

Pre-build debugging: Add ls -la in the pre_build phase to verify your source files are present and the working directory is correct.

Cost Considerations

Running a Hugo site on S3 with CodeBuild is one of the most cost-effective hosting options:

• S3 static hosting: Pennies per month for low-to-moderate traffic sites.
• CodeBuild: 100 free build minutes per month on the general1.small instance. Most Hugo builds complete in under 60 seconds.
• CloudFront (optional): Adding a CDN improves performance and provides HTTPS, with a generous free tier of 1TB transfer per month.

Use AWS Budgets to set spending alerts and avoid surprises.