Stacktape

Sign up

Stacktape

Sign up



Hosting Buckets

Overview

  • Hosting buckets are ideal for serving static content(such as static website) and client rendered applications to your users across the world.
  • Contents of your application are distributed through CDN. By distributing and caching content across 310+ globally dispersed Points of Presence (PoPs - also called edge locations) you can significantly decrease the latency of data delivery as well as reduce load on your application.
  • Hosting buckets come secured(with automatic TLS) out of the box
  • If your use-case requires more control over bucket configuration take a look at the bucket resource.

Under the hood

Under the hood, the hosting bucket has two main components:

  • S3 bucket - an object(file) storage where your assets are uploaded and stored. For more information about S3 refer to AWS docs.
  • Cloudfront CDN distribution - distributes and caches your app assets across the world. For more information about Cloudfront refer to AWS docs.

Basic usage

You can configure properties hosting bucket by simply setting upload directory path:

  • 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 or bucket:sync commands, contents of the folder is uploaded to the bucket

Copy

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 what type of content type you are hosting.

Based of that Stacktape will configure HTTP headers of uploaded files and CDN behavior.

Supported content types:

  • static-website:
    • sets cache-control header value for all uploaded files to public, max-age=0, s-maxage=31536000, must-revalidate.
    • this setup caches all the content on the CDN but never caches files in the browser.
  • gatsby-static-website:
  • 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.

Copy

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

Custom domains

Custom domain names

If you do not have a custom domain and want one, read the section Registering domain on the Domains and TLS certificates page.

If you already have an existing domain and you wish to use it with your app, there are two approaches:

  1. Using Stacktape to manage domains and certs - you must use Route53 in your AWS account as your DNS.
  2. Using 3rd party DNS provider - such as GoDaddy, Cloudflare etc. You must handle domains and generate certificates yourself.

For more information about domain management options, refer to Domains and TLS 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.

Copy

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

Using 3rd party DNS

To use 3rd party provider follow these steps:

  1. Create/import a custom TLS certificate for your domain in AWS console. Copy certificate ARN; you will need it in the next step.
  2. After the certificate is validated (Issued), assign your domain to your resource:
    • use the ARN of your certificate as customCertificateArn
    • disable DNS record creation (because you are using third party DNS)

Copy

resources:
myWebsite:
type: hosting-bucket
properties:
uploadDirectoryPath: ./dist
customDomains:
- domainName: mydomain.com
disableDnsRecordCreation: true
customCertificateArn: <<ARN_OF_YOUR_CERTIFICATE>>
  1. After you deploy your hosting bucket, you can find the domain name in Stacktape console in:

    Your project and stage > Click on your Hosting Bucket resource to see its (CDN) domain

    Once you have the domain name, you can point DNS record to this domain using your DNS provider:

    • Use ALIAS record type for root domains (i.e mydomain.com)
    • Use CNAME record type for subdomains (i.e www.mydomain.com or staging.mydomain.com

Edge lambda functions

  • 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-bucket
    • onResponse - 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

For more information refer to Edge lambda functions page.

onRequest
onResponse
onOriginRequest
onOriginResponse

Copy

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

Need help? Ask a question on Discord or info@stacktape.com.