diff --git a/.github/workflows/on-docs-update.yml b/.github/workflows/on-docs-update.yml index 2d77560..b22774a 100644 --- a/.github/workflows/on-docs-update.yml +++ b/.github/workflows/on-docs-update.yml @@ -3,7 +3,7 @@ name: Build and Deploy Documentation on: push: branches: - - main + - documentation paths: - 'docs/**' workflow_dispatch: diff --git a/docs-old/advanced-usage.md b/docs-old/advanced-usage.md deleted file mode 100644 index aff807b..0000000 --- a/docs-old/advanced-usage.md +++ /dev/null @@ -1,106 +0,0 @@ -# CloudFront Hosting Toolkit - Self-managed Frontend Hosting on AWS - -## Advanced usage - -- [Build Configuration](#build-configuration) -- [Custom Framework Configurations](#custom-framework-configurations) -- [Initialize the Deployment Without Built-In Wizard](#initialize-a-deployment-without-built-in-wizard) - - - -### How it works behind the scene - -After running `cloudfront-hosting-toolkit init`, CloudFront Hosting Toolkit will create a folder named `cloudfront-hosting-toolkit` in the directory where the tool is executed. This `cloudfront-hosting-toolkit` folder contains essential files for managing your deployment process: - -1. `cloudfront-hosting-toolkit-config.json`: This JSON file stores the configuration settings gathered during the `init` process. You can review and modify these settings as needed. - -2. `cloudfront-hosting-toolkit-config.yml`: This YAML file is necessary for CodeBuild to build your website. It contains build configuration information, ensuring that your website is built correctly. - -3. `cloudfront-hosting-toolkit-cff.js`: This JavaScript file encapsulates the code utilized by the CloudFront Function for URL rewriting. Given the variability in rules based on the framework, this file is accessible for modifications at any time, enabling the addition of additional logic required to execute at the edge. - -4. During deployment, the CLI generates log files to capture important information and log messages. These log files are named using the format `YYYY-MM-DD_HH-MM-SS.log` and are stored in the `cloudfront-hosting-toolkit` folder. You can review these logs to troubleshoot any deployment issues or monitor the deployment process. - -Make sure to keep these files in the `cloudfront-hosting-toolkit` folder for seamless management of your futur deployments. - -### Core Project Components: CodeBuild and CloudFront Functions - - -Two essential components play vital roles in deploying and managing hosted websites: - -- **AWS CodeBuild**: CodeBuild serves as the engine responsible for building and deploying websites. It automates the entire process, from assembling files to pushing them to the hosting bucket. This automation streamlines the deployment pipeline, minimizing manual tasks and enabling swift updates. - -- **Amazon CloudFront Function**: The CloudFront function is actively deployed for every viewer request, offering two key functionalities: - - Reads the key-value store to retrieve the folder name, directing users to the latest S3 folder and ensuring consistent access to the most up-to-date content. - - URL rewriting, enabling efficient service for Single Page Applications (SPAs) and statically generated sites. - -A CloudFront Function is allocated for each framework, and it is copied into your current directory during the initialization phase. The reason for having one template per framework is because, for example, between single-page application (SPA) and non-SPA websites, different rewrite rules are required. Additionally, a user may utilize a framework that necessitates specific rewrite rules. - -The function templates can be located within this [folder](../resources/cff_templates). - -If your website requires customization beyond the out-of-the-box configurations, you'll likely find yourself making modifications to either the CodeBuild spec YAML file or the CloudFront function code. - -### CodeBuild in the Deployment Pipeline - -CodeBuild plays a critical role in the CloudFront Hosting Toolkit deployment pipeline. It is responsible for building your website's source code and preparing it for deployment. This encompasses tasks like code compilation, the creation of deployment artifacts, and pushing files to the hosting bucket. - -### Build configuration - -The `cloudfront-hosting-toolkit-config.yml` file is a vital component in the deployment process. It serves as a configuration file for CodeBuild, specifying the exact steps to build your website based on your chosen framework (if applicable) or handling the deployment of static files without any build process. - -Here's how the `cloudfront-hosting-toolkit-config.yml` file works: - -1. **Framework-Specific Build**: If your website is built using a specific framework (e.g., React, Angular, Vue), the `cloudfront-hosting-toolkit-config.yml` file contains instructions and commands tailored to that framework. CloudFront Hosting Toolkit provides predefined build configurations for several popular frameworks, ensuring that your website is built correctly. - -2. **No Build**: If your website does not use a specific framework or requires no build process, the `cloudfront-hosting-toolkit-config.yml` file will specify the necessary commands to copy the static files to the destination bucket directly. - -3. **Folder Naming**: After a successful build or file copy, the CloudFront Hosting Toolkit CLI creates a new folder in the destination bucket, named with the commit ID of your latest changes. This ensures that each deployment is uniquely identified, making it easy to manage and roll back to previous versions if needed. - -If you ever need to make further customizations, such as installing additional libraries required for your build or adjusting library versions, you can easily achieve this by modifying the `cloudfront-hosting-toolkit-config.yml` file and running `cloudfront-hosting-toolkit deploy` once again. - - -### Custom Framework Configurations - -The project is designed to support a wide range of popular frameworks by providing flexible build configurations. You can easily adapt our project to suit your preferred framework. Below are some of the frameworks that are supported with corresponding build configurations: - -- AngularJs -- NextJs -- ReactJs -- VueJs - - -The goal is to provide a versatile and adaptable project that empowers you to work with the framework of your choice. - - -If you're using a framework that isn't listed above, you can bring your own configuration to tailor CloudFront Hosting Toolkit to your needs. Follow these steps to create a custom configuration: -1. **Build configuration** - - Locate one existing configuration templates at `/installation_folder/resources/build_config_templates/`. - - Create a new configuration and keeping the `aws s3 cp` command in your new file and following this naming pattern: `hosting_YOURFRAMEWORKNAME.yml`. - - Customize the configuration file to fit your specific requirements, including any additional libraries or version changes. - -2. **CloudFront Function** - - - Locate an existing CloudFront Function source file located at `/installation_folder/resources/cff_templates/`. - - Create your own JavaScript file for URL rewriting following the naming convention `index_YOURFRAMEWORKNAME.js`. -3. **Run the CLI again** - - Run the `cloudfront-hosting-toolkit init` command again. - - When prompted, select your custom configuration from the list. - -This way, you can seamlessly integrate your unique framework configuration into CloudFront Hosting Toolkit and deploy your website with ease. - -### Initialize a deployment without built in wizard - -Instructions for Deploying Based on Your Deployment Type: - -1. If you want to deploy from S3 and build the sources yourself: - - - Use the `solution.context.json.template.s3` template file located in the current folder. Replace the placeholders in the selected template file with your own values, and then copy it to the `./cloudfront-hosting-toolkit` folder with the name `solution.context.json`. - - Copy the `s3_build_config.yml` file located in the `resources/build_config_templates` folder to the `cloudfront-hosting-toolkit` folder. - - Copy the `index_basic.js` file located in the `resources/cff_templates` folder to the `cloudfront-hosting-toolkit` folder. - -2. If you want the sources to be built by the built-in pipeline and deploy from GitHub: - - - Use the `solution.context.json.template.github` template file located in the current folder. Replace the placeholders in the selected template file with your own values, and then copy it to the `cloudfront-hosting-toolkit` folder with the name `solution.context.json`. - - Use the `hosting_YOURFRAMEWORKNAME.yml` template file located in the `resources/build_config_templates` folder to customize your deployment then copy it to the `cloudfront-hosting-toolkit` folder. - - Use the `index_YOURFRAMEWORKNAME.js` template file located in the `resources/cff_config_templates` folder to customize your deployment then copy it to the `cloudfront-hosting-toolkit` folder. - - diff --git a/docs-old/faq.md b/docs-old/faq.md deleted file mode 100644 index 04d516f..0000000 --- a/docs-old/faq.md +++ /dev/null @@ -1,24 +0,0 @@ -# CloudFront Hosting Toolkit - Self-managed Frontend Hosting on AWS - -## FAQ - -**Is it necessary to acquire a domain name in advance or before deploying my website?** - - Yes, it's advisable to acquire your desired domain name before configuring it for your website if you want to associate a custom domain name with your website. You have the flexibility to purchase the domain name either through your AWS account or from any other DNS provider of your choice. This ensures that you have ownership and control over the domain name as you proceed with the website configuration. - - -**I've successfully deployed my website using the tool, and now I'd like to configure a custom domain name. What are the steps I should follow?** - - To use a domain name for your deployed website, follow these steps: - - - Run the `init` command again to initiate the setup process. - - - During the setup process, select the option that allows you to specify your desired domain name. - - - Once you've made the desired domain name selection, proceed with the deployment by running the `deploy` command. - - -**Is it possible to deploy a website that was built without utilizing any frontend framework using this tool?** - -Yes, you can. -The tool is designed to be versatile and adaptable to your specific needs. If you've built your website without utilizing any frontend framework, our tool will automatically detect that no framework is in use. As a result, there won't be any build step required. diff --git a/docs-old/roadmap.md b/docs-old/roadmap.md deleted file mode 100644 index f0c6d38..0000000 --- a/docs-old/roadmap.md +++ /dev/null @@ -1,37 +0,0 @@ -## Roadmap - - -This roadmap outlines the planned features and enhancements for the CloudFront Hosting Toolkit project. - -## Image Optimization - -**Explanation**: Optimization module dedicated to enhancing website performance. This module's function is to reduce image sizes to enhance website performance, ensuring faster page load times and an overall enhanced user experience. - - -## PR Preview - -**Explanation**: PR Preview (Pull Request Preview) functionality allows developers to preview a branch before merging it into the main codebase. - - -## Authorization - -**Explanation**: Enhancing authorization for precise user access control and permissions. - -## A/B Testing - -**Explanation**: A/B testing enables you to compare different versions of your website to determine which performs better. - -## Instant Rollback - -**Explanation**: Instant rollback capability enables rapid reversion to a prior application version in case of unexpected issues during new deployments. - -## Server-Side Rendering (SSR) - -**Explanation**: Server-Side Rendering (SSR) enhances website performance and SEO by rendering pages on the server before sending them to the client. - -## Routes - -**Explanation**: Routing features offer navigation to backend resources. - - -This roadmap outlines key features, but we are open to incorporating new ideas based on your feedback. We remain dedicated to the ongoing improvement of CloudFront Hosting Toolkit, with the goal of empowering you to create and host exceptional web applications. We are excited about implementing these enhancements to provide an even better hosting experience for our users diff --git a/docs-old/troubleshooting.md b/docs-old/troubleshooting.md deleted file mode 100644 index 61619c3..0000000 --- a/docs-old/troubleshooting.md +++ /dev/null @@ -1,67 +0,0 @@ -# CloudFront Hosting Toolkit - Self-managed Frontend Hosting on AWS - -## Troubleshooting Guide - -This guide provides solutions to common issues you might encounter while using CloudFront Hosting Toolkit. - - -### Issue 1: Source Stage Failing - - -Symptoms: The source stage in the CodePipeline is failing, and your deployment is not proceeding as expected. - - -1. Verify GitHub App Integration - - Check GitHub Integration: Ensure that your AWS account is properly connected to your GitHub repository. Follow these steps to verify: - Log in to your AWS account. - Navigate to the AWS CodePipeline console. - Locate the pipeline associated with your project. - Check if the source action in your pipeline is configured to use the GitHub App. - -2. GitHub Repository Access: Ensure that the GitHub repository you wish to deploy is accessible to the GitHub App integrated with your AWS account. - In your GitHub repository, go to "Settings" > "Access" or similar options. - Confirm that the GitHub App has the necessary permissions to access the repository. - If required, adjust the GitHub App's access permissions to include read access to the repository. - -By following these steps, you can verify the GitHub App integration between your AWS account and the repository you intend to deploy. This should help resolve issues related to the source stage failing in your CodePipeline. - -After fixing the permissions, trigger the pipeline again by choosing "Release change" or similar action in the AWS CodePipeline console. This will initiate a new pipeline run with the corrected settings. - - -### Issue 2: Build Stage Failing - -1. Check CodeBuild Logs: To diagnose the issue, start by examining the CodeBuild logs for the build stage. Follow these steps: - - Log in to your AWS account. - - Navigate to the AWS CodePipeline console. - - Locate the pipeline associated with your project. - - Find the build stage within the pipeline. - - Access the CodeBuild logs for this stage. - - Review the logs for error messages, warnings, or any other indicators of the issue causing the build to fail. - -2. Customize Build Configuration: If the logs indicate that the build configuration needs customization, make the necessary changes following these steps: - - Locate your build configuration file (e.g., buildConfigurationFile.yml) that defines the build steps and commands. - - Customize the file as needed, which may involve modifying build commands, dependencies, or environment variables. - - Save your changes. - -3. Deploy Again: After customizing the build configuration, redeploy your project by following these steps: - - Trigger the pipeline again by choosing "Release change" or a similar action in the AWS CodePipeline console. - - This will initiate a new pipeline run with the updated build configuration. - -By checking the CodeBuild logs and customizing the build configuration as required, you can address issues related to the build stage failing in your AWS CodePipeline. This process helps diagnose and resolve build-related problems, ensuring a smoother deployment process for your project. - -### Issue 3: Website display issue - -Please ensure to review the CloudFront function being utilized along with its associated rewrite rules, as they might not align correctly with the framework currently in use. -There are two options available: - -1. You can rerun the `init` command and select a different framework if the initially chosen one wasn't suitable. -2. You have the option to modify the code of the CloudFront function and then execute the deployment command again -The file containing the code for your CloudFront Function can be found at this location. `cloudfront-hosting-toolkit/cloudfront-hosting-toolkit-cff.js` - -Inspect the source code of the function in your local directory, make modifications as needed, and then execute the `deploy` command again. - - - - diff --git a/docs/src/content/docs/advanced/bring-your-own-framework.md b/docs/src/content/docs/advanced/bring-your-own-framework.md index 4d5c079..739bcdb 100644 --- a/docs/src/content/docs/advanced/bring-your-own-framework.md +++ b/docs/src/content/docs/advanced/bring-your-own-framework.md @@ -1,45 +1,100 @@ --- -title: Custom Frameworks +title: Bring your own framework --- -While CloudFront Hosting Toolkit supports many popular frameworks out-of-the-box, you can configure it for custom frameworks. +While CloudFront Hosting Toolkit supports many popular frameworks out-of-the-box, you can configure it for custom frameworks. This allows you to create a reusable configuration for your specific framework that can be used across multiple projects. -## Steps to Integrate Your Framework +## Steps to Integrate Your Custom Framework -1. Create a custom build configuration file named `hosting_YOURFRAMEWORKNAME.yml` in the `cloudfront-hosting-toolkit` folder. -2. Create a custom CloudFront Function file named `index_YOURFRAMEWORKNAME.js` in the same folder. -3. Run `cloudfront-hosting-toolkit init` again and select your custom framework when prompted. +1. Locate the CLI installation folder of CloudFront Hosting Toolkit. + +2. Create two new files and place them in the following subfolders of the CLI installation folder: + - A custom build configuration file named `hosting_YOUR_FRAMEWORK_NAME.yml` in the `resources/build_config_templates` folder. + - A custom CloudFront Function file named `index_YOUR_FRAMEWORK_NAME.js` in the `resources/cff_templates` folder. + +3. After creating and placing these files, run `cloudfront-hosting-toolkit init` in your project directory and select your custom framework when prompted. + +## File Naming Convention and Locations + +It's crucial to follow the exact naming format for both files and place them in the correct folders: + +- The build configuration file must be named: `hosting_YOUR_FRAMEWORK_NAME.yml` + Place this file in: `/resources/build_config_templates/` + +- The CloudFront Function file must be named: `index_YOUR_FRAMEWORK_NAME.js` + Place this file in: `/resources/cff_templates/` + +Replace YOUR_FRAMEWORK_NAME with the name of your framework. + +For example: +- For a framework called "MySSG": + - `resources/build_config_templates/hosting_MySSG.yml` + - `resources/cff_templates/index_MySSG.js` +- For a framework called "Custom React": + - `resources/build_config_templates/hosting_Custom_React.yml` + - `resources/cff_templates/index_Custom_React.js` + +Note: The framework name displayed in the init wizard will be taken from the YOUR_FRAMEWORK_NAME part of the filename. For example, if your files are named `hosting_Custom_React.yml` and `index_Custom_React.js`, the framework name displayed will be "Custom React". + +## Build Configuration File Structure + +When creating your custom build configuration file (`hosting_YOUR_FRAMEWORK_NAME.yml`), keep in mind the following structure and requirements: + +```yaml +version: 0.2 +phases: + build: + commands: + # Your custom build commands go here + - command1 + - command2 + # ... + # The following command is mandatory and must be the last command + - aws s3 cp ./ s3://$DEST_BUCKET_NAME/$CODEBUILD_RESOLVED_SOURCE_VERSION/ --recursive #don't change this line +``` + +Important notes: +1. You can include any number of custom build commands to suit your framework's needs. +2. The last command (the `aws s3 cp` command) is mandatory and must be included exactly as shown above. +3. `$DEST_BUCKET_NAME` and `$CODEBUILD_RESOLVED_SOURCE_VERSION` are environment variables automatically available in CodeBuild. Do not change these variable names. ## Example: Custom Static Site Generator -For a custom static site generator called "MySSG": +Let's create a configuration for a custom static site generator called "MySSG": -1. Create `hosting_myssg.yml`: +1. Create `hosting_MySSG.yml` in the `/resources/build_config_templates/` folder: ```yaml version: 0.2 phases: - install: - runtime-versions: - nodejs: 18 build: commands: + - npm install - npm run generate -artifacts: - base-directory: output - files: - - '**/*' + - cd dist # Assuming 'dist' is your output directory + # The following command is mandatory + - aws s3 cp ./ s3://$DEST_BUCKET_NAME/$CODEBUILD_RESOLVED_SOURCE_VERSION/ --recursive #don't change this line ``` -2. Create `index_myssg.js`: +2. Create `index_MySSG.js` in the `/resources/cff_templates/` folder: ```javascript function handler(event) { var request = event.request; var uri = request.uri; - - // Custom URL rewriting logic here - + + // Custom URL rewriting logic for MySSG + if (uri.endsWith('/')) { + request.uri += 'index.html'; + } else if (!uri.includes('.')) { + request.uri += '.html'; + } + return request; } -``` \ No newline at end of file +``` + +3. Run `cloudfront-hosting-toolkit init` in your project directory and select "MySSG" when prompted for the framework. + + +By following these steps and ensuring your build configuration file includes the mandatory S3 copy command, you can create and use custom framework configurations across multiple projects, streamlining your deployment process for unique or in-house frameworks. \ No newline at end of file diff --git a/docs/src/content/docs/advanced/configuration.md b/docs/src/content/docs/advanced/configuration.md index 3696a15..d38dfe7 100644 --- a/docs/src/content/docs/advanced/configuration.md +++ b/docs/src/content/docs/advanced/configuration.md @@ -2,11 +2,29 @@ title: Advanced Configuration --- -CloudFront Hosting Toolkit offers various advanced configuration options to tailor the deployment process to your specific needs. +CloudFront Hosting Toolkit offers various advanced configuration options to tailor the deployment process to your specific needs. After running the `init` command, you have the flexibility to customize your deployment before running the `deploy` command. + +## Configuration Files + +After running `cloudfront-hosting-toolkit init`, three configuration files are created in your project's `cloudfront-hosting-toolkit` folder: + +1. `cloudfront-hosting-toolkit-config.yml` +2. `cloudfront-hosting-toolkit-cff.js` +3. `cloudfront-hosting-toolkit-config.json` + +You can edit these files to customize your deployment before running the `deploy` command. + +## Customization Process + +1. **Initial Setup**: Run `cloudfront-hosting-toolkit init` to generate the default configuration files. +2. **Customization**: Edit the configuration files as needed (optional). +3. **Deployment**: Run `cloudfront-hosting-toolkit deploy` to deploy your infrastructure using either the default or customized configuration. + +Note: You can deploy using the default configuration and later customize as needed. After making changes to any configuration file, simply run the `deploy` command again to update your infrastructure. ## Custom Build Configurations -You can customize the build process by modifying the `cloudfront-hosting-toolkit-config.yml` file in your project's `cloudfront-hosting-toolkit` folder. This file contains instructions for CodeBuild on how to build your website. +Modify the `cloudfront-hosting-toolkit-config.yml` file to customize the build process. This file contains instructions for CodeBuild on how to build your website. Example for a React app: @@ -30,14 +48,129 @@ artifacts: ## CloudFront Function Customization -The `cloudfront-hosting-toolkit-cff.js` file in your project's `cloudfront-hosting-toolkit` folder contains the CloudFront Function code for URL rewriting. You can modify this to implement custom routing logic. +The `cloudfront-hosting-toolkit-cff.js` file contains the CloudFront Function code for URL rewriting. Modify this file to implement custom routing logic for your application. -## Environment Variables +Example of a basic URL rewriting function: -You can set environment variables for your build process by adding them to your `cloudfront-hosting-toolkit-config.yml` file: +```javascript +function handler(event) { + var request = event.request; + var uri = request.uri; + + // Add custom routing logic here + if (uri.endsWith('/')) { + request.uri += 'index.html'; + } else if (!uri.includes('.')) { + request.uri += '.html'; + } + + return request; +} +``` -```yaml -env: - variables: - KEY: "value" +## Project Configuration + +The `cloudfront-hosting-toolkit-config.json` file contains your project's configuration settings. You can modify this file to change settings such as the repository URL, branch name, or framework. + +Example: + +```json +{ + "repoUrl": "https://github.com/USERNAME/REPOSITORY.git", + "branchName": "main", + "framework": "react" +} ``` + +## Potential Modifications + +Here are some examples of modifications you might make to each configuration file: + +### 1. cloudfront-hosting-toolkit-config.yml + +This file controls your build process. Some potential modifications include: + +- Changing the Node.js version: + ```yaml + runtime-versions: + nodejs: 16 # Change to a different version if needed + ``` + +- Adding a testing step: + ```yaml + phases: + pre_build: + commands: + - npm install + - npm run test # Add this line to run tests before building + ``` + +- Customizing the artifact output: + ```yaml + artifacts: + base-directory: dist # Change if your build output is in a different folder + files: + - '**/*' + - '!**/*.map' # Exclude source map files + ``` + +### 2. cloudfront-hosting-toolkit-cff.js + +This file contains your CloudFront Function for URL rewriting. You might modify it to: + +- Handle single-page application (SPA) routing: + ```javascript + function handler(event) { + var request = event.request; + var uri = request.uri; + + // Route all requests to index.html for SPA + if (!uri.includes('.')) { + request.uri = '/index.html'; + } + + return request; + } + ``` + +- Implement custom error page routing: + ```javascript + function handler(event) { + var request = event.request; + var uri = request.uri; + + if (uri === '/404') { + request.uri = '/custom-404.html'; + } else if (uri === '/500') { + request.uri = '/custom-500.html'; + } + + return request; + } + ``` + +### 3. cloudfront-hosting-toolkit-config.json + +This file contains your project configuration. Possible modifications include: + +- Changing the deployment branch: + ```json + { + "repoUrl": "https://github.com/USERNAME/REPOSITORY.git", + "branchName": "develop", // Change to deploy from a different branch + "framework": "react" + } + ``` + +- Adding a custom domain: + ```json + { + "repoUrl": "https://github.com/USERNAME/REPOSITORY.git", + "branchName": "main", + "framework": "react", + "domainName": "www.example.com", // Add your custom domain + "hostedZoneId": "Z1234567890ABC" // Add your Route 53 hosted zone ID + } + ``` + +Remember, you can always revert to the default configuration by re-running the `init` command, but this will overwrite any existing customizations. Always backup your custom configurations before reinitializing. \ No newline at end of file diff --git a/docs/src/content/docs/troubleshooting/guide.md b/docs/src/content/docs/troubleshooting/guide.md index 6c65c5e..6caa41f 100644 --- a/docs/src/content/docs/troubleshooting/guide.md +++ b/docs/src/content/docs/troubleshooting/guide.md @@ -1,27 +1,40 @@ --- -title: Troubleshooting Guide +title: Troubleshooting guide --- -### 1. Debugging Steps +If you encounter issues while using CloudFront Hosting Toolkit, follow this guide to diagnose and resolve common problems. -1. Use `cloudfront-hosting-toolkit status` to check the current state of your deployment. -2. Review the logs in the `cloudfront-hosting-toolkit` folder for detailed operation logs. -3. Use AWS Management Console to inspect the state of individual resources (S3, CloudFront, CodePipeline). +## 1. General debugging steps +1. Use `cloudfront-hosting-toolkit status` to check the current state of your deployment. +2. Review the logs in the `cloudfront-hosting-toolkit` folder (named with the format `YYYY-MM-DD_HH-MM-SS.log`) for detailed operation logs. +3. Use AWS Management Console to inspect the state of individual resources (S3, CloudFront, CodePipeline, CodeBuild). -### 2. Deployment Fails +## 2. Deployment fails - **Check AWS Credentials**: Ensure your AWS CLI is correctly configured with the right permissions. -- **Verify Build Configuration**: Ensure your `cloudfront-hosting-toolkit-config.yml` is correctly formatted. +- **Verify Build Configuration**: Ensure your `cloudfront-hosting-toolkit-config.yml` is correctly formatted and contains all necessary commands. +- **Review CodeBuild Logs**: Check the CodeBuild project in AWS Console for specific build failure reasons. +- **GitHub Connection Issues**: For GitHub-based deployments, ensure the AWS CodeStar connection is properly set up and authorized. +- **Project Structure and Framework Compatibility**: Verify that your project structure is correct and compatible with the chosen framework. If the framework specified in the JSON file is incorrect, you can: + - Manually change it in the `cloudfront-hosting-toolkit-config.json` file to one of the supported values. + - Customize the build configuration in `cloudfront-hosting-toolkit-config.yml` to use the correct commands for building your website. + +## 3. Website not updating after deployment + +- **Review CodeBuild Logs**: Often, the issue lies in the build configuration. Inspect the CodeBuild logs in the AWS Console to understand if the build process completed successfully and if all expected files were generated. +- **Verify Build Configuration**: Ensure your `cloudfront-hosting-toolkit-config.yml` is correctly configured for your framework and project structure. Pay special attention to build commands and output directories. +- **Review CloudFront Function**: Ensure the function is correctly routing to the new folder. Check the function logs in CloudFront console. +- **Check Key-Value Store (KVS)**: Verify that the KVS was updated with the new deployment information (commit ID). You can check this in the CloudFront console under the Functions section. + +## 4. Custom domain issues -### 2. Website not updating after deployment +- **Certificate Validation**: If using a custom domain, ensure the SSL/TLS certificate is properly validated in AWS Certificate Manager. +- **DNS Configuration**: Verify that your domain's DNS settings are correctly pointing to the CloudFront distribution. -- **Check Cache Invalidation**: Verify that CloudFront cache invalidation completed successfully. -- **Review CloudFront Function**: Ensure the function is correctly routing to the new folder. -- **Check DynamoDB**: Verify that the Key-Value store was updated with the new deployment information. ## Getting Help -- **Documentation**: Refer to our comprehensive documentation for detailed information. -- **GitHub Issues**: Check existing issues or create a new one on our GitHub repository. +- **Documentation**: Refer to our comprehensive documentation for detailed information on each feature and process. +- **GitHub Issues**: Check existing issues or create a new one on our [GitHub repository](https://github.com/awslabs/cloudfront-hosting-toolkit).