Stacktape
Stacktape

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.

This should be the path to the directory containing the content you want to host, such as the output directory of your website's build process.

The contents of this folder will be uploaded to the bucket during the deploy, codebuild:deploy, or bucket:sync commands.

resources:
  myWebsite:
    type: 'hosting-bucket'
    properties:
      uploadDirectoryPath: ./dist
HostingBucket  API reference
type
Required
properties.uploadDirectoryPath
Required
properties.excludeFilesPatterns
properties.hostingContentType
Default: static-website
properties.customDomains
properties.disableUrlNormalization
properties.edgeFunctions
properties.errorDocument
properties.indexDocument
Default: /index.html
properties.injectEnvironment
properties.writeDotenvFilesTo
properties.useFirewall
properties.fileOptions
properties.routeRewrites
overrides

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 the Cache-Control header to public, max-age=0, s-maxage=31536000, must-revalidate for all uploaded files.
    • This setup caches all content on the CDN but never in the browser.

  • gatsby-static-website:

  • single-page-app:

    • Optimizes headers for Single-Page Applications.
    • html files are never cached to ensure users always get the latest content after a deployment.
    • All other assets (e.g., .js, .css) are cached indefinitely. You should always add a content hash to your filenames to ensure users receive new versions after updates. For more details, see the documentation for your bundler (e.g., webpack).
    • Sets up the necessary CDN redirects for a single-page app.
resources:
  myWebsite:
    type: hosting-bucket
    properties:
      uploadDirectoryPath: ./dist
      hostingContentType: 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

When you connect a custom domain, Stacktape automatically:

  • Creates DNS records: A DNS record is created to point your domain name to the resource.
  • Adds TLS certificates: Stacktape issues and attaches a free, AWS-managed TLS certificate to handle HTTPS.

To manage a custom domain, it must first be added to your AWS account as a hosted zone, and your domain registrar's name servers must point to it. For more details, see the Adding a domain guide.

resources:
  myWebsite:
    type: hosting-bucket
    properties:
      uploadDirectoryPath: ./dist
      hostingContentType: single-page-app
      customDomains:
        - domainName: example.com

Using a 3rd-party DNS

To use a domain from a provider like GoDaddy or Cloudflare:

  1. Create or import a TLS certificate for your domain in the AWS Certificate Manager console and copy its ARN.
  2. Add the customDomains configuration to your hosting bucket, using the certificate ARN and disabling DNS record creation.
resources:
  myWebsite:
    type: hosting-bucket
    properties:
      uploadDirectoryPath: ./dist
      customDomains:
        - domainName: mydomain.com
          disableDnsRecordCreation: true
          customCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>
  1. After deploying, find the hosting bucket's domain name in the Stacktape Console.
  2. In your DNS provider's dashboard, create a CNAME or ALIAS 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 an edge-lambda-function with this hosting bucket to be executed at different stages:

  • onRequest: Executed when the CDN receives a request from a client, before checking the cache and before the request is forwarded to the hosting bucket.
  • onResponse: Executed before returning a response to the client.

Potential Use Cases:

  • Generating an immediate HTTP response without checking the cache or forwarding to the bucket.
  • Modifying the request (e.g., rewriting the URL or headers) before forwarding to the bucket.
EdgeFunctionsConfig  API reference
Parent:HostingBucketorCdnRouteRewrite
onRequest
onResponse
onOriginRequest
onOriginResponse
resources:
  authFunction:
    type: edge-lambda-function
    properties:
      packaging:
        type: stacktape-lambda-buildpack
        properties:
          entryfilePath: auth-function.ts


  myWebsite:
    type: hosting-bucket
    properties:
      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.

name

  • AWS (physical) name of the bucket

  • Usage: $ResourceParam('<<resource-name>>', 'name')
arn

  • Arn of the bucket

  • Usage: $ResourceParam('<<resource-name>>', 'arn')
cdnDomain

  • Default domain of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnDomain')
cdnUrl

  • Default url of the CDN distribution (only available if you DO NOT configure custom domain names for the CDN).

  • Usage: $ResourceParam('<<resource-name>>', 'cdnUrl')
cdnCustomDomains

  • 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')
cdnCustomDomainUrls

  • 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')

Contents