S3 Static Site

This document contains information about the S3 Static Site service supported in Handel. This Handel service sets up an S3 bucket and CloudFront distribution for your static website.


This service requires you to have the external AWS CLI installed in order to use it. See the AWS documentation for help on installing it.

If you are running Handel inside CodePipeline, you should already have the AWS CLI pre-installed.

Service Limitations

No CORS Support

This service doesn’t support configuring CORS support on the static site bucket. It just uses the default CORS configuration for S3 buckets:

  • Origin: *
  • Methods: GET
  • Headers: Authorization

No Redirects Support

This service doesn’t yet support redirects (i.e. ‘www.mysite.com’ to ‘mysite.com’) to your static site bucket.


This service takes the following parameters:

Parameter Type Required Default Description
type string Yes   This must always be s3staticsite for this service type.
path_to_code string Yes   The path to the folder where your static website resides. This will be uploaded to your S3 static site bucket.
bucket_name string No <appName>-<environmentName>-<serviceName>-<serviceType> The name of the bucket to create. This name must be globally unique across all AWS accounts, so ‘myBucket’ will likely be taken. :)
versioning string No disabled Whether to enable versioning on the bucket. Allowed values: ‘enabled’, ‘disabled’
index_document string No index.html The name of the file in S3 to serve as the index document.
error_document string No error.html The name of the file in S3 to serve as the error document.
cloudfront CloudFront Configuration No   Configuration for CloudFront. If not specified, CloudFront is not enabled.
tags Resource Tags No   Any tags you want to apply to your S3 bucket

CloudFront Configuration

The cloudfront section is defined by the following schema:

Parameter Type Required Default Description
https_certificate string No   The ID of an Amazon Certificate Manager certificate to use for this site
minimum_https_protocol string No ‘TLSv1.2_2018’ The minimum allowed HTTPS protocol version. Valid values are listed in the Cloudfront API Docs.
dns_names List<string> No   The DNS names to use for the CloudFront distribution. See DNS Records.
price_class string No all one of 100, 200, or all. See CloudFront Pricing.
logging enabled|disabled No enabled Whether or not to log all calls to Cloudfront.
min_ttl TTL Values No 0 Minimum time to cache objects in CloudFront
max_ttl TTL Values No 1 year Maximum time to cache objects in CloudFront
default_ttl TTL Values No 1 day Default time to cache objects in CloudFront

TTL Values

min_ttl, max_ttl, and default_ttl control how often CloudFront will check the source bucket for updated objects. They are specified in seconds. In the interest of readability, Handel also offers some duration shortcuts:

Alias Duration in seconds
second(s) 1
minute(s) 60
hour(s) 3600
day(s) 86400
year 31536000

So, writing this:

cloudfront_max_ttl: 2 days

is equivalent to:

cloudfront_max_ttl: 172800

Example Handel File

This Handel file shows an S3 Static Site service being configured:

version: 1

name: s3-static-website

      type: s3staticsite
      path_to_code: ./_site/
      versioning: enabled
      index_document: index.html
      error_document: error.html
        price_class: all
        https_certificate: 6afbc85f-de0c-4ee9-b7d7-28b961eca135
        mytag: myvalue

Depending on this service

The S3 Static Site service cannot be referenced as a dependency for another Handel service.

Events produced by this service

The S3 Static Site service does not produce events for other Handel services.

Events consumed by this service

The S3 Static Site service does not consume events from other Handel services.