Code Monkey home page Code Monkey logo

awslabs / cloudfront-hosting-toolkit Goto Github PK

View Code? Open in Web Editor NEW
94.0 7.0 4.0 19.75 MB

CloudFront Hosting Toolkit offers the convenience of a managed frontend hosting service while retaining full control over the hosting and deployment infrastructure to make it your own.

License: Apache License 2.0

TypeScript 50.38% JavaScript 48.76% HTML 0.86%
aws-acm aws-acm-certificate aws-code-build aws-codepipeline aws-lambda aws-route53 aws-step-functions cloudfront cloudfront-distribution cloudfront-functions

cloudfront-hosting-toolkit's Introduction

CloudFront Hosting Toolkit

CloudFront Hosting Toolkit is an open-source command-line tool designed to simplify the deployment and management of fast, secure frontend applications on AWS. It offers the convenience of a managed frontend hosting service while giving developers full control over their hosting and deployment infrastructure.

What is CloudFront Hosting Toolkit?

CloudFront Hosting Toolkit is a comprehensive solution that automates the process of setting up and managing a robust, scalable frontend hosting infrastructure on AWS. It leverages several AWS services, including CloudFront, S3, CodePipeline, and Lambda, to create a powerful hosting environment tailored for modern web applications.

Key features include:

  • ๐Ÿš€ Automated setup of AWS resources for frontend hosting
  • ๐Ÿ”„ Continuous deployment pipeline for GitHub and S3-based workflows
  • ๐ŸŒ Optimized content delivery through CloudFront
  • ๐Ÿ”’ Built-in security features including HTTPS and security headers
  • ๐Ÿ”— Custom domain support with automatic SSL/TLS certificate management
  • ๐Ÿ› ๏ธ Flexible configuration options for various frontend frameworks

How It Works

CloudFront Hosting Toolkit streamlines the deployment process through a simple CLI interface. It automatically provisions and configures necessary AWS resources, handles the deployment pipeline, and manages content delivery through CloudFront.

For a detailed explanation of the architecture and workflow, please refer to our Architecture documentation.

Why Use CloudFront Hosting Toolkit?

  • Simplicity: Deploy complex frontend hosting setups with just a few commands.
  • Speed: Leverage CloudFront's global CDN for fast content delivery.
  • Security: Automatic HTTPS configuration and security headers.
  • Flexibility: Support for various frontend frameworks and deployment sources.
  • Cost-Effective: Utilize AWS services efficiently without unnecessary overhead.
  • Full Control: Retain the ability to customize and extend your infrastructure.

Getting Started

Check out our documentation for comprehensive guides on setting up and using the Cloudfront Hosting Toolkit!

Requirements

  • Node.js 18+
  • AWS CLI 2+ configured with your AWS account
  • (Optional) A GitHub account for GitHub-based deployments

Installation

npm install -g @aws/cloudfront-hosting-toolkit

Quick Start

  1. Initialize your project:

    cloudfront-hosting-toolkit init

    The animated GIF below demonstrates the initialization process sample

  2. Deploy your website:

    cloudfront-hosting-toolkit deploy

    The animated GIF below demonstrates the deployment process sample

For more detailed instructions and advanced usage, please refer to our CLI Guide.

Example Commands

# Show domain name
cloudfront-hosting-toolkit show

# Check deployment status
cloudfront-hosting-toolkit status

# Remove hosting infrastructure
cloudfront-hosting-toolkit delete

Architecture

Technical diagram

CloudFront Hosting Toolkit sets up a comprehensive AWS architecture for your frontend hosting:

  • Source Control: GitHub repository or S3 bucket
  • CI/CD: AWS CodePipeline for automated builds and deployments
  • Build Process: AWS CodeBuild for compiling and creating deployment artifacts
  • Storage: S3 buckets for hosting website files
  • Content Delivery: CloudFront for global content distribution
  • Routing: CloudFront Functions for request handling and routing
  • Orchestration: Step Functions for managing deployment processes
  • State Management: KVS for storing deployment state information

This architecture ensures a scalable, performant, and maintainable hosting solution for your frontend applications.

Advanced Usage

CloudFront Hosting Toolkit offers flexibility in how it can be used:

  • CLI: Use the Command-Line Interface for a straightforward, step-by-step deployment process.
  • CDK Construct: Leverage the CloudFront Hosting Toolkit as a ready-made L3 CDK construct for seamless integration into your AWS CDK projects.
  • CDK Source Code: Customize the CDK source code to tailor the infrastructure to your specific requirements.

For more information on how to use CloudFront Hosting Toolkit, including advanced usage scenarios and in-depth customization options, please refer to our extensive documentation in the Advanced section.

Documentation

Roadmap

For information about upcoming features and improvements, please see our Roadmap.

License

This library is licensed under the Apache-2.0 License.

cloudfront-hosting-toolkit's People

Contributors

amazon-auto avatar cornelcroi avatar dependabot[bot] avatar lmammino avatar niklas-palm avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

cloudfront-hosting-toolkit's Issues

Bug: Domain name validation doesn't accept TLDs longer than 6 characters

Expected Behaviour

Domain name input should accept any valid domain name.

Current Behaviour

Domains with TLDs longer than 6 characters, such as .services, are rejected.

Code snippet

โœ” Do you own a domain name that you would like to use? โ€บ Yes


? Please provide your domain name in the following formats: www.mydomainname.com or mydomainname.com ? โ€บ test.services
โ€บ Domain name format must be www.mydomainname.com or mydomainname.com

Possible Solution

https://github.com/awslabs/cloudfront-hosting-toolkit/blob/main/bin/cli/shared/constants.ts#L54

Change the current regex:

  /^[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,6}$/i;

to:

  /^[a-z0-9]+([\-\.]{1}[a-z0-9]+)*\.[a-z]{2,}$/i;

Steps to Reproduce

  1. Run cloudfront-hosting-toolkit init
  2. Follow the steps until you get to the prompt Please provide your domain name in the following formats: www.mydomainname.com or mydomainname.com
  3. Enter any domain name with a TLD longer than 6 characters, e.g. test.services

Native CodePipline steps

Use case

granted this seems to be beta phase in development, but it would be good to remove the step functions from the pipeline
image

Solution/User Experience

step functions in pipelines are a temporary solution to something that should be native/built-in steps/actions in CodePipeline.

This will make for a more standard pipeline flow without the need for custom step functions.

Action structure reference

ActionTypeId:
      Category: Invoke
      Owner: AWS
      Version: 1
      Provider: CloudFrontHosting    
Configuration:
      CloudFrontHostingAction: UpdateKeyValue

ActionTypeId:
      Category: Invoke
      Owner: AWS
      Version: 1
      Provider: CloudFrontHosting    
Configuration:
      CloudFrontHostingAction: Purge


## Or a simple consolidated action
ActionTypeId:
      Category: Invoke
      Owner: AWS
      Version: 1
      Provider: CloudFrontHosting    
Configuration:
      Phase: alpha|beta|prod

Additional questions

How does canary/blue-green work with the pipelines?

Organization best practices Architecture

Expected Behaviour

standardised/harmonised best practice, consider the following AWS Guidance on Organization best practices for production.
CDK
image
Amplify
image
CodeCatalyst
image

Current Behaviour

image

Code snippet

Organization best practices documented here: https://docs.aws.amazon.com/cdk/v2/guide/best-practices.html

Possible Solution

Standardise the best practice CICD workflow.

Steps to Reproduce

Check the AWS doco

Bug:/Idea: `npx next export` is not supported anymore in Next.js

Expected Behaviour

I used the default next.js starter kit npx create-next-app@latest nextjs-blog --use-pnpm --example "https://github.com/vercel/next-learn/tree/main/basics/learn-starter"

My expected behaviour would be that the deploy step is deploying the static files.

Current Behaviour

The build step fails with the following logs:

[Container] 2024/06/05 06:01:35.090350 Running command npx next export
73 | โจฏ
74 | `next export` has been removed in favor of 'output: export' in next.config.js.
75 | Learn more: https://nextjs.org/docs/app/building-your-application/deploying/static-exports
76 | ย 
77

I know that only SSG and SPA are supported right now. But I think the developer experience could be improved if the CLI locally already fails or if the build command understands that next version xyz is not supporting this command anymore.

Code snippet

1. `npx create-next-app@latest nextjs-blog --use-pnpm --example "https://github.com/vercel/next-learn/tree/main/basics/learn-starter"`
2. `cloudfront-hosting-toolkit init`
3. `cloudfront-hosting-toolkit deploy`

Possible Solution

Show a warning locally / break locally

Steps to Reproduce

  1. npx create-next-app@latest nextjs-blog --use-pnpm --example "https://github.com/vercel/next-learn/tree/main/basics/learn-starter"
  2. cloudfront-hosting-toolkit init
  3. cloudfront-hosting-toolkit deploy

It doesn't work

Expected Behaviour

it works

Current Behaviour

your doco is wrong, and it doesn't work. fix it you Billion $ company!
image

image

Code snippet

yeah nah

Possible Solution

No response

Steps to Reproduce

fix is

Feature request: Document Remix and Next.js planned support

Exciting to see a new tool in this space.

Use case

As a someone interested in this tool I'd like to know about current and planned support for the "default" next.js and and remix support

Solution/User Experience

Next.js and Remix docs both nudge devs to a architecture that includes a lambda. Next has "static export" and Remix has "spa mode" which are compatible with cloudfront-hosting-toolkit now - but these are not defaults.

Make current and planned support clearer in the readme or roadmap.

Alternative solutions

No response

Other thoughts

I can see in the roadmap there are plans to support SSR. Does this include running code on lambdas like next.js' api routes or remix (not spa mode)?

Hosting next.js serverlessly is notoriously difficult, so I'd understand if that wasn't planned ๐Ÿ˜…. Remix is supposed to much easier, though I haven't done it myself.

Bug: Route53 A record not usiong the correct target domain

Expected Behaviour

A Route53 A record with alias target, targeting the Cloudfront domain.

Current Behaviour

A Route53 A record with alias target, targeting a substring of Cloudfront domain.

Code snippet

N/A

Possible Solution

When the alias record is created, the a record target should be the cloudfront domain name. However, there's a bug where the first 8 characters of the domain name are omitted:

const cFCNAMEExists = await checkCFCNAMEExists(
  hostingConfiguration.domainName,
  domainName.substring(8),
  hostingConfiguration.hostedZoneId
);

This is the location in the code. Will submit PR.

Steps to Reproduce

N/A

You didn't fix #3

Expected Behaviour

fixed

Current Behaviour

not fixed

Code snippet

fix it

Possible Solution

fix it

Steps to Reproduce

fix #3

try npm i

Feature request: Allow creation of multiple pipelines per repository

Use case

When using AWS CDK to create CI/CD pipelines for multiple branches in a repository, we need to create separate pipelines for each branch within the same AWS account.

However, the current implementation generates pipeline names in the format [repoOwner]-[repoName], which leads to the error "[pipeline name] already exists" when trying to create additional pipelines for the same repository.

This limits us to creating only one pipeline per repository in a single AWS account.

Solution/User Experience

Enhance the pipeline creation functionality in AWS CDK to support multiple pipelines per repository within the same AWS account.

This would allow users to set up separate pipelines for different branches or environments without the need for multiple AWS accounts.

Alternative solutions

No response

Failed to create bin at <project>/node_modules/.bin/cloudfront-hosting-toolkit. ENOENT: no such file or directory, open '<project>/node_modules/@aws/cloudfront-hosting-toolkit/bin/cli/index.js'

Expected Behaviour

npm i -g @aws/cloudfront-hosting-toolkit does not install the binary as expected

Current Behaviour

Running both:

npm i -g @aws/[email protected]

or

npm i -g @aws/[email protected]

Produces the following warning and the binary is not created:

Failed to create bin at <project>/node_modules/.bin/cloudfront-hosting-toolkit. ENOENT: no such file or directory, open '<project>/node_modules/@aws/cloudfront-hosting-toolkit/bin/cli/index.js'

It seem to work for version 1.1.9 (npm i -g @aws/[email protected])

Code snippet

npm i -g @aws/cloudfront-hosting-toolkit@1.1.11


or

```bash
npm i -g @aws/cloudfront-hosting-toolkit@1.1.10


### Possible Solution

Looks like the `bin/cli/index.js` file is not included in the package published on npm

### Steps to Reproduce

```bash
npm i -g @aws/[email protected]

or

npm i -g @aws/[email protected]

Bug: Validation Error Detected

Expected Behaviour

Successful deploy.

Current Behaviour

We were attempting to deploy a static (HTML/CSS only) website, and the deploy aborted with the following error:

โŒ hosting-main-www-guthries-com-main failed: Error: The stack named hosting-main-www-guthries-com-main failed creation, it may need to be manually deleted from the AWS console: ROLLBACK_COMPLETE: 1 validation error detected: Value at 'pipeline.stages.1.member.actions.1.member.namespace' failed to satisfy constraint: Member must satisfy regular expression pattern: [A-Za-z0-9@-_]+ (Service: AWSCodePipeline; Status Code: 400; Error Code: ValidationException; Request ID: 8ad71865-afd2-4f77-9e88-4928bd3eecb7; Proxy: null)
at FullCloudFormationDeployment.monitorDeployment (/usr/lib/node_modules/@aws/cloudfront-hosting-toolkit/node_modules/aws-cdk/lib/index.js:451:10568)
at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
at async Object.deployStack2 [as deployStack] (/usr/lib/node_modules/@aws/cloudfront-hosting-toolkit/node_modules/aws-cdk/lib/index.js:454:199716)
at async /usr/lib/node_modules/@aws/cloudfront-hosting-toolkit/node_modules/aws-cdk/lib/index.js:454:181438

We're using 'fish' shell, but also tried 'bash' shell.

AWS CLI aws-cli/2.0.17 Python/3.7.3 Linux/5.15.153.1-microsoft-standard-WSL2 botocore/2.0.0dev21

(will try upgrading)

Code snippet

`cloudfront-hosting-toolkit deploy`

Possible Solution

The problem is the 'period' or 'full stop' in our Git repo name. We regularly name our Git repos after app domains / applications etc. Like guthries.com, or www.foo.com etc., This causes the pipeline to fail with an invalid namespace name that contain the period character - which is not in this regex pattern: [A-Za-z0-9@-_]+ The cli and generated outputs need to be escaped to remove periods or special characters and replace them with the allowed characters of the regex expression. I'm guessing that maxLength should be checked as well.

Steps to Reproduce

cloudfront-hosting-toolkit init
cloudfront-hosting-toolkit deploy

Feature request: Make the CloudFront Distribution available as a property

Use case

I would like to use the CloudFront Distribution domain to configure a Congito User Pool Client.

Solution/User Experience

I would like to be able to do:

const { distribution } = new Hosting(this, 'Hosting', {...});

Alternative solutions

Currently, I have used `tryFindChild` on the construct node itself to drill down to what I need.

Example apps

Use case

Example TODO app would help consolidate the concept

Solution/User Experience

  • Something vanilla with webcomponents so that we don't have to maintain React/Angular versions. Maybe Typescript with esbuild so that the full CDK stack + app can be TS.

  • When you provide the example app, think about testing in the CICD pipeline.

  • Run the Jest test for the CDK.
  • Unit Tests
  • Integration tests
  • UI tests
  • Since you're providing a CICD concept
  • show best of breed DevSecOps tests
  • JUnit reports which are supported in CodePipeline.
  • Should have monitoring of pipeline
  • Should have best of breed opinions on manual approvals & alerts
  • Should have monitoring of app once deployed
  • Should have app metrics in the monitoring
  • leverage Blue/Green/Canary deployments with CodeDeploy.
  • If not why not?
  • Provide a more advanced example that has a backend.

Alternative solutions

No response

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.