Hosting Buckets
Hosting buckets are designed for serving static content, such as single-page applications or static websites. They distribute your content through a CDN with over 300 points of presence (PoPs) worldwide, ensuring low latency for your users. Hosting buckets are also secure by default, with automatic TLS.
If you need more control over the bucket's configuration, consider using a standard bucket instead.
Under the hood, a hosting bucket uses two main components:
- An S3 bucket to store your assets.
- A CloudFront CDN distribution to cache and serve your assets.
Basic usage
You can configure a hosting bucket by simply providing the path to the directory you want to upload.
Path to the directory that contains content you wish to host.
This can be output directory of your website build process(built website) or any other directory containing static content you wish to serve.
During
deploy
,codebuild:deploy
orbucket:sync
commands, contents of the folder is uploaded to the bucket
resources:myWebsite:type: 'hosting-bucket'properties:uploadDirectoryPath: ./dist
Hosting content type
You can specify the type of content you are hosting. Based on this, Stacktape will configure the HTTP headers of the uploaded files and the CDN behavior.
Supported content types:
- static-website:
- sets
cache-control
header value for all uploaded files topublic, max-age=0, s-maxage=31536000, must-revalidate
. - this setup caches all the content on the CDN but never caches files in the browser.
- sets
- gatsby-static-website:
- optimizes headers for static websites built using Gatsby according to Gatsby caching recommendations.
- single-page-app:
- optimizes headers for a Single page application
html
files are never cached (so that when you re-deploy your website, your users always get the latest content)- All other assets (.js, .css, etc.) are cached indefinitely. You should ALWAYS add a content hash to the filename, so that your users always get a new version of your website after you deploy it. To learn how to add a content hash to your files, refer to the docs of your bundler, for example webpack docs.
- Sets up correct CDN redirects for single page app.
resources:myWebsite:type: hosting-bucketproperties:uploadDirectoryPath: ./disthostingContentType: single-page-app
Custom domains
You can use a custom domain for your hosting bucket. If you don't have one, you can register one through Stacktape.
If you already have a domain, you can either let Stacktape manage it (if you use AWS Route 53 for DNS) or use a third-party DNS provider.
For more details, see the Domains and Certificates page.
Using Stacktape to manage domains and certs
Connecting a custom domain to the resource does 2 things:
- Creates DNS records:
- If you use your custom domain with a resource, Stacktape automatically creates a DNS record (during deploy) pointing the specified domain name to the resource.
- Adds TLS certificates
- Stacktape takes care of issuing and attaching correct (free, AWS-managed) certificate to the resource. This means, you do not have to deal with TLS termination(HTTPS).
- If you want to use your own certificates, you can configure
customCertificateArns
.
To manage a custom domain, it first needs to be added to your AWS account. This means that a hosted zone (collection of records managed together for a given domain) for your domain exists in your AWS account and your domain registrar's name servers are pointing to it. To learn more, refer to Adding a domain guide.
resources:myWebsite:type: hosting-bucketproperties:uploadDirectoryPath: ./disthostingContentType: single-page-appcustomDomains:- domainName: example.com
Using a 3rd-party DNS
To use a domain from a provider like GoDaddy or Cloudflare:
- Create or import a TLS certificate for your domain in the AWS Certificate Manager console and copy its ARN.
- Add the
customDomains
configuration to your hosting bucket, using the certificate ARN and disabling DNS record creation.
resources:myWebsite:type: hosting-bucketproperties:uploadDirectoryPath: ./distcustomDomains:- domainName: mydomain.comdisableDnsRecordCreation: truecustomCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>
- After deploying, find the hosting bucket's domain name in the Stacktape Console.
- In your DNS provider's dashboard, create a
CNAME
orALIAS
record pointing to the hosting bucket's domain name.
Edge Lambda functions
You can run Lambda functions at the edge to customize the content that the CDN delivers. For more information, see the Edge Lambda Functions page.
You can associate
edge-lambda-function
with hosting-bucket to be executed:onRequest
- function is executed when CDN receives a request from a client(viewer) before checking CDN cache and before request is forwarded to hosting-bucketonResponse
- function is executed before returning the response to the client(viewer)
Potential use-cases for using edge functions:
- generating immediate HTTP response without the need to check CDN cache or forward to the bucket
- modifying request (i.e rewrite url, headers etc) before forwarding to the bucket
resources:authFunction:type: edge-lambda-functionproperties:packaging:type: stacktape-lambda-buildpackproperties:entryfilePath: auth-function.tsmyWebsite:type: hosting-bucketproperties:edgeFunctions:onRequest: authFunction
Referenceable parameters
The following parameters can be easily referenced using $ResourceParam directive directive.
To learn more about referencing parameters, refer to referencing parameters.
AWS (physical) name of the bucket
- Usage:
$ResourceParam('<<resource-name>>', 'name')
Arn of the bucket
- Usage:
$ResourceParam('<<resource-name>>', 'arn')
Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnDomain')
Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnUrl')
Comma-separated list of custom domain names assigned to the CDN (only available if you configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnCustomDomains')
Comma-separated list of custom domain name URLs of the CDN (only available if you configure custom domain names for the CDN).
- Usage:
$ResourceParam('<<resource-name>>', 'cdnCustomDomainUrls')