Stacktape
Stacktape

Hosting Bucket

This example shows a basic hosting bucket configuration.

Hosting bucket resource

  • Hosting bucket resource can be used to host your static website or other static content
  • It combines the power of S3 Bucket (stores the static data) and Cloudfront CDN (distributes data across the globe)

Basic example

resources:
  myHostingBucket:
    type: hosting-bucket
    properties:
      # Path to the directory 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` or `bucket:sync` commands, contents of the folder is uploaded to the bucket
      #
      # - Type: string
      # - Required: true
      uploadDirectoryPath: ./path/to/uploadDirectoryPath
      # Configures which files should be excluded from upload (glob patterns).
      #
      # - Relative to the `uploadDirectoryPath`
      # - Following example patterns might include spaces due to docs rendering issues. Remove them before using these patterns in your config:
      # - Example pattern excluding all files ending in **.js.map**: `** /*.js.map`
      # - Example pattern excluding all files in directory named **test**: `test/**`
      #
      # - Type: array<string>
      # - Required: false
      excludeFilesPatterns:
        - example-value
      # Based on what content type is chosen, configures 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**:
      # - optimizes headers for static websites built using [Gatsby](https://www.gatsbyjs.com/)
      # according to [Gatsby caching recommendations](https://www.gatsbyjs.com/docs/caching/).
      # - **single-page-app**:
      # - optimizes headers for a [Single page application](https://en.wikipedia.org/wiki/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](https://webpack.js.org/guides/caching/).
      # - Sets up correct CDN redirects for single page app.
      #
      # - Type: enum: [gatsby-static-website, single-page-app, static-website]
      # - Required: false
      # - Allowed values: [gatsby-static-website, single-page-app, static-website]
      hostingContentType: gatsby-static-website
      # Attaches a custom domains to this hosting bucket
      #
      # 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](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html)
      # > (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](https://docs.stacktape.com/other-resources/domains-and-certificates/#adding-domain).
      #
      # - Type: array<object (reference)>
      # - Required: false
      customDomains:
        - domainName: api.example.com
          customCertificateArn: example-value
      # Disables URL normalization (ability to use clean urls without the `.html` extension)
      #
      # - URL normalization is enabled by default.
      # - URL normalization is useful when you want to serve HTML files from the bucket
      # - When the URL normalization is enabled, the CDN is able to fetch correct HTML files
      # from the bucket even when incomplete URL is used (without the `.html` extension)
      # - This enables you to use URLs such as `<<my-domain.com>>/about` instead of urls
      # `<<my-domain.com>>/about.html` or `<<my-domain.com>>/about/index.html`
      #
      # - Type: boolean
      # - Required: false
      # - Default: false
      disableUrlNormalization: false
      # Configures Edge function triggers
      #
      # - 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
      #
      # - Type: object
      # - Required: false
      edgeFunctions:
        # Name of the edge-lambda-function in the config
        #
        # - `onRequest` function is triggered when CDN receives a request from a client(viewer):
        # - You can modify the request before forwarding it to the origin
        # - You can return immediate response to the client(viewer)
        # - You can make network calls to external resources to confirm user credentials, or fetch additional content
        # - The body of the request is exposed to the function with some restrictions
        # (refer to [AWS docs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-functions-restrictions.html#lambda-at-edge-restrictions-request-body) for more details)
        #
        # - Type: string
        # - Required: false
        onRequest: example-value
        # Name of the edge-lambda-function in the config
        #
        # - `onResponse` function is triggered before CDN returns response to the client(viewer):
        # - You can modify the response (headers, cookies) before returning to the client
        # - The function does not execute in following cases:
        # - When the origin returns an HTTP status code of 400 or higher.
        # - When the response is generated from a function that was triggered by a viewer request event (`onRequest` function).
        #
        # - Type: string
        # - Required: false
        onResponse: example-value
        # Name of the edge-lambda-function in the config
        #
        # > Use `onOriginRequest` trigger only if you are an advanced user and know what you are doing.
        # > Using this trigger can **override the default behaviour configured by Stacktape**.
        # > Stacktape uses pre-configured lambdas together with this trigger when using CDN with:
        # > - **bucket** - Stacktape uses this trigger with pre-configured lambda to correctly resolve URLs
        # > - **web-service, http-api-gateway, application-load-balancer** - Stacktape uses this trigger with pre-configured lambda to adjust headers before sending to origin
        # - `onOriginRequest` function is triggered after CDN receives a request from a client(viewer) but before the request is send to the origin:
        # - This means that function is NOT triggered when response is found in the cache (as no request to origin needs to happen)
        # - You can modify the request before forwarding it to the origin
        # - You can return immediate response to the client(viewer) - the response will be cached same way as if it was from the origin
        # - You can make network calls to external resources to confirm user credentials, or fetch additional content
        # - The body of the request is exposed to the function with some restrictions
        # (refer to [AWS docs](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/edge-functions-restrictions.html#lambda-at-edge-restrictions-request-body) for more details)
        #
        # - Type: string
        # - Required: false
        onOriginRequest: example-value
        # Name of the edge-lambda-function in the config
        #
        # - `onOriginResponse` function is triggered after origin returns response but before it is sent back to the client(viewer):
        # - You can modify the response (headers, cookies) before returning to the client - the response will be cached same way as if it was from the origin
        # - You can update the response status.
        #
        # - Type: string
        # - Required: false
        onOriginResponse: example-value
      # Custom error document URL
      #
      # - Error document is requested if the original request to the origin responds with an error code `404`.
      # - Example: `/error.html`
      #
      # - Type: string
      # - Required: false
      errorDocument: example-value
      # Custom index (root) document served for requests with path `/`
      #
      #
      # - Type: string
      # - Required: false
      # - Default: /index.html
      indexDocument: /index.html
      # Injects referenced parameters to all HTML files present in the `uploadDirectoryPath`
      #
      # - These parameters can be accessed by any javascript script
      # - They can be accessed using `window.STP_INJECTED_ENV.<<VARIABLE_NAME>>`
      # - Useful, when you want to automatically reference parameters such as URL of your API Gateway ID of your Userpool, which
      # are only known after the deployment
      # - This simplifies the development of fullstack apps
      #
      # - Type: array<object (reference)>
      # - Required: false
      injectEnvironment:
        - name: example-name
      # Injects referenced parameters to all HTML files present in the `uploadDirectoryPath`
      #
      # - Writes injected environment into .env files inside the specified directory
      # - The name of the generated file will be `.<<stage>>.env`
      # - If the file already exists, these variables will be merged with the existing variables
      #
      # - Type: string
      # - Required: false
      writeDotenvFilesTo: example-value
      # Name of the 'web-app-firewall' resource type that will be used to protect this hosting bucket
      #
      # - You can use `web-app-firewall` to protect your resources from common web exploits that could affect application availability, compromise security, or consume excessive resources.
      # - Web app firewall protects your application by filtering dangerous requests coming to your app.
      # You can read more about the firewall [in our docs](https://docs.stacktape.com/security-resources/web-app-firewalls/).
      # > Note: Because this resource uses CDN under the hood, `scope` of the `web-app-firewall` (used by this resource) must be set `cdn`
      #
      # - Type: string
      # - Required: false
      useFirewall: example-value
      # File options allow you to manually set headers (such as `cache-control` or `content-type`) of files that match the filter pattern
      #
      # - Type: array<object (reference)>
      # - Required: false
      fileOptions:
        - includePattern: example-value
          excludePattern: example-value
      # Enables you to redirect specific requests to a different origin
      #
      # - Each incoming request to the CDN is first evaluated against route rewrites. The requested path is compared with path pattern specified in route rewrite.
      # - If the requested path matches the path pattern specified by route rewrite, the request is sent to the configured route.
      # - Route rewrites are evaluated in order. The first match is where the request will be sent to.
      # - If no match is found, request is sent to the default origin (the one that the CDN is attached to).
      #
      # **Example use cases**:
      # - Most of the content you are serving is a static content
      # served from a bucket (static website). Some content however needs to be
      # rendered dynamically by a Lambda function. You can route paths that need
      # to be rendered dynamically to the lambda function.
      # - You want to cache your `jpg` files longer than
      # other files. You can create route rewrite that will catch every path
      # ending with `jpg` and set custom caching options for these paths.
      #
      # - Type: array<object (reference)>
      # - Required: false
      routeRewrites:
        - path: example-value
          routePrefix: example-value

RouteTo alternatives

application-load-balancer

This example shows how to configure routeto using application-load-balancer.

resources:
  myHostingBucket:
    type: hosting-bucket
    properties:
      routeRewrites:
        items:
          #
          # - Type: object
          # - Required: true
          routeTo:
            #
            # - Type: string
            # - Required: true
            type: application-load-balancer
            #
            # - Type: object
            # - Required: true
            properties:
              # Name of the Load balancer
              #
              # - Type: string
              # - Required: true
              loadBalancerName: myLoadBalancerName
              # Port of the Load balancer listener
              #
              # - You need to specify listener port if the load balancer you are routing to uses custom listeners.
              #
              # - Type: number
              # - Required: false
              listenerPort: 3000
              # Explicitly sets the origin domain name you wish to use when forwarding to load balancer
              #
              # - This is required only if the load balancer has no `customDomains` attached and listener uses `customCertificateArns`
              #
              # - Type: string
              # - Required: false
              originDomainName: myOriginDomainName

http-api-gateway

This example shows how to configure routeto using http-api-gateway.

resources:
  myHostingBucket:
    type: hosting-bucket
    properties:
      routeRewrites:
        items:
          #
          # - Type: object
          # - Required: true
          routeTo:
            #
            # - Type: string
            # - Required: true
            type: http-api-gateway
            #
            # - Type: object
            # - Required: true
            properties:
              # Name of the HTTP Api Gateway
              #
              # - Type: string
              # - Required: true
              httpApiGatewayName: myHttpApiGatewayName

function

This example shows how to configure routeto using function.

resources:
  myHostingBucket:
    type: hosting-bucket
    properties:
      routeRewrites:
        items:
          #
          # - Type: object
          # - Required: true
          routeTo:
            #
            # - Type: string
            # - Required: true
            type: function
            #
            # - Type: object
            # - Required: true
            properties:
              # Name of the Web Service resource
              #
              # - Type: string
              # - Required: true
              functionName: myFunctionName

custom-origin

This example shows how to configure routeto using custom-origin.

resources:
  myHostingBucket:
    type: hosting-bucket
    properties:
      routeRewrites:
        items:
          #
          # - Type: object
          # - Required: true
          routeTo:
            #
            # - Type: string
            # - Required: true
            type: custom-origin
            #
            # - Type: object
            # - Required: true
            properties:
              # Domain name of the custom origin.
              #
              # Example: `mydomain.com` or `domain.example.com`
              #
              # - Type: string
              # - Required: true
              domainName: api.example.com
              # Protocol to use when connecting to custom origin.
              #
              #
              # - Type: enum: [HTTP, HTTPS]
              # - Required: false
              # - Default: HTTPS
              # - Allowed values: [HTTP, HTTPS]
              protocol: HTTP
              # Port of the custom origin.
              #
              # By default port number 443 is used for `HTTPS` origins and port number 80 is used for `HTTP` origins.
              #
              # - Type: number
              # - Required: false
              # - Default: 443
              port: 3000

bucket

This example shows how to configure routeto using bucket.

resources:
  myHostingBucket:
    type: hosting-bucket
    properties:
      routeRewrites:
        items:
          #
          # - Type: object
          # - Required: true
          routeTo:
            #
            # - Type: string
            # - Required: true
            type: bucket
            #
            # - Type: object
            # - Required: true
            properties:
              # Name of the bucket
              #
              # - Type: string
              # - Required: true
              bucketName: my-example-bucket
              # Disables URL normalization (ability to use clean urls without the `.html` extension)
              #
              # - URL normalization is enabled by default.
              # - URL normalization is useful when you want to serve HTML files from the bucket
              # - When the URL normalization is enabled, the CDN is able to fetch correct HTML files
              # from the bucket even when incomplete URL is used (without the `.html` extension)
              # - This enables you to use URLs such as `<<my-domain.com>>/about` instead of urls
              # `<<my-domain.com>>/about.html` or `<<my-domain.com>>/about/index.html`
              #
              # - Type: boolean
              # - Required: false
              # - Default: false
              disableUrlNormalization: false

Contents