|
1 |
| -# github-actions-deploy-serverless-website |
| 1 | +# Deploy serverless website |
| 2 | + |
| 3 | +GitHub action to deploy anything into a bucket, adding the options to add a CDN and use a Domain (if hosted in Route53) with certificates. |
| 4 | + |
| 5 | +This action will copy the files from the defined folder into an S3 bucket, defining the content type and serving ALL OF THEM PUBLICLY. |
| 6 | + |
| 7 | +## Requirements |
| 8 | + |
| 9 | +1. Files to publish |
| 10 | +2. An AWS Account |
| 11 | +3. If domain and cert wanted, registered domain in AWS. |
| 12 | + |
| 13 | +### 1. Files to publish |
| 14 | +Will grab everything defined in `aws_spa_source_folder` and push it to a bucket. |
| 15 | +Define `aws_spa_root_object` if different than `index.html` |
| 16 | + |
| 17 | +### 2. An AWS account |
| 18 | +You'll need [Access Keys](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-appendix-sign-up.html) from an [AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/) |
| 19 | + |
| 20 | +### 3. CERTIFICATES - Only for AWS Managed domains with Route53 |
| 21 | +If `domain_name` is defined, we will look up for a certificate with the name of that domain (eg. `example.com`). We expect that certificate to contain both `example.com` and `*.example.com`. |
| 22 | + |
| 23 | +Setting `create_root_cert` to `true` will create this certificate with both `example.com` and `*.example.com` for you, and validate them. (DNS validation). |
| 24 | + |
| 25 | +Setting `create_sub_cert` to `true` will create a certificate **just for the subdomain**, and validate it. |
| 26 | + |
| 27 | +> :warning: Be very careful here! **Created certificates are fully managed by Terraform**. Therefor **they will be destroyed upon stack destruction**. |
| 28 | +
|
| 29 | + |
| 30 | +## Example usage |
| 31 | + |
| 32 | +Create `.github/workflow/deploy.yaml` with the following to build on push. |
| 33 | + |
| 34 | +### Example usage |
| 35 | +```yaml |
| 36 | +name: Basic deploy |
| 37 | +on: |
| 38 | + push: |
| 39 | + branches: [ main ] |
| 40 | + |
| 41 | +jobs: |
| 42 | + Deploy-SPA: |
| 43 | + runs-on: ubuntu-latest |
| 44 | + |
| 45 | + steps: |
| 46 | + - name: Create deploy-bucket-only |
| 47 | + |
| 48 | + with: |
| 49 | + aws_access_key_id: ${{ secrets.AWS_ACCESS_KEY_ID_SANDBOX}} |
| 50 | + aws_secret_access_key: ${{ secrets.AWS_SECRET_ACCESS_KEY_SANDBOX}} |
| 51 | + aws_default_region: us-east-1 |
| 52 | + |
| 53 | + tf_action: 'apply' |
| 54 | + tf_state_bucket_destroy: true |
| 55 | + |
| 56 | + aws_spa_cdn_enabled: true |
| 57 | + |
| 58 | + aws_r53_domain_name: examplex.com |
| 59 | + aws_r53_sub_domain_name: spa |
| 60 | +``` |
| 61 | +
|
| 62 | +## Customizing |
| 63 | +
|
| 64 | +### Inputs |
| 65 | +1. [Action defaults](#action-defaults-inputs) |
| 66 | +1. [AWS](#aws-inputs) |
| 67 | +1. [Terraform options](#terraform-options-inputs) |
| 68 | +1. [SPA Settings](#spa-settings-inputs) |
| 69 | +1. [Certificate](#certificate-inputs) |
| 70 | +
|
| 71 | +The following inputs can be used as `step.with` keys |
| 72 | +<br/> |
| 73 | +<br/> |
| 74 | + |
| 75 | +#### **Action defaults Inputs** |
| 76 | +| Name | Type | Description | |
| 77 | +|------------------|---------|------------------------------------| |
| 78 | +| `checkout` | Boolean | Set to `false` if the code is already checked out. (Default is `true`). | |
| 79 | +<hr/> |
| 80 | +<br/> |
| 81 | + |
| 82 | +#### **AWS Inputs** |
| 83 | +| Name | Type | Description | |
| 84 | +|------------------|---------|------------------------------------| |
| 85 | +| `aws_access_key_id` | String | AWS access key ID | |
| 86 | +| `aws_secret_access_key` | String | AWS secret access key | |
| 87 | +| `aws_default_region` | String | AWS default region. Defaults to `us-east-1` | |
| 88 | +| `aws_role_to_assume` | String | AWS Role to assume. Default is empty. | |
| 89 | +| `aws_resource_identifier` | String | Set to override the AWS resource identifier for the deployment. Defaults to `${GITHUB_ORG_NAME}-${GITHUB_REPO_NAME}-${GITHUB_BRANCH_NAME}`. Use with destroy to destroy specific resources. | |
| 90 | +| `additional_tags` | JSON | Add additional tags to the terraform [default tags](https://www.hashicorp.com/blog/default-tags-in-the-terraform-aws-provider), any tags put here will be added to all provisioned resources.| |
| 91 | +<hr/> |
| 92 | +<br/> |
| 93 | + |
| 94 | +#### **Terraform options inputs** |
| 95 | +| Name | Type | Description | |
| 96 | +|------------------|---------|------------------------------------| |
| 97 | +| `tf_action` | String | Option to run Terraform `apply` / `destroy` action. Will run `plan` if nothing defined. | |
| 98 | +| `tf_plan_show_details` | Boolean | Set to true to show a detailed output from Terraform plan. | |
| 99 | +| `tf_state_bucket` | String | AWS S3 bucket name to use for Terraform state. Defaults to `${org}-${repo}-{branch}-tf-state` | |
| 100 | +| `tf_state_bucket_destroy` | Boolean | Force purge and deletion of S3 bucket defined if terraform destroy action succeded. | |
| 101 | +<hr/> |
| 102 | +<br/> |
| 103 | + |
| 104 | +#### **SPA Settings inputs** |
| 105 | +| Name | Type | Description | |
| 106 | +|------------------|---------|------------------------------------| |
| 107 | +| `aws_spa_source_folder` | String | Source folder for files to be published. Will ignore any hidden file. Defaults to root folder of the calling repo if nothing defined. | |
| 108 | +| `aws_spa_root_object` | Boolean | Root object to be served as entry-point. Defaults to `index.html`. | |
| 109 | +| `aws_spa_website_bucket_name` | String | AWS S3 bucket name to use for the public files. Defaults to `${org}-${repo}-{branch}-sp` | |
| 110 | +| `aws_spa_cdn_enabled` | Boolean | Enable or disables the use of CDN. Defaults to `false`. | |
| 111 | +<hr/> |
| 112 | +<br/> |
| 113 | + |
| 114 | +#### **Certificate Inputs** |
| 115 | +| Name | Type | Description | |
| 116 | +|------------------|---------|------------------------------------| |
| 117 | +| `aws_r53_domain_name` | String | Define the root domain name for the application. e.g. `bitovi.com`. | |
| 118 | +| `aws_r53_sub_domain_name` | String | Define the sub-domain part of the URL. Defaults to `${GITHUB_ORG_NAME}-${GITHUB_REPO_NAME}-${GITHUB_BRANCH_NAME}`. | |
| 119 | +| `aws_r53_root_domain_deploy` | Boolean | Deploy application to root domain. Will create root and www records. Default is `false`. | |
| 120 | +| `aws_r53_cert_arn` | String | Define the certificate ARN to use for the application. | |
| 121 | +| `aws_r53_create_root_cert` | Boolean | Generates and manage the root cert for the application. Default is `false`. | |
| 122 | +| `aws_r53_create_sub_cert` | Boolean | Generates and manage the sub-domain certificate for the application. Default is `false`. | |
| 123 | +<hr/> |
| 124 | +<br/> |
| 125 | + |
| 126 | + |
| 127 | +## Note about resource identifiers |
| 128 | + |
| 129 | +Most resources will contain the tag `${GITHUB_ORG_NAME}-${GITHUB_REPO_NAME}-${GITHUB_BRANCH_NAME}`, some of them, even the resource name after. |
| 130 | +We limit this to a 60 characters string because some AWS resources have a length limit and short it if needed. |
| 131 | + |
| 132 | +We use the kubernetes style for this. For example, kubernetes -> k(# of characters)s -> k8s. And so you might see some compressions are made. |
| 133 | + |
| 134 | +For some specific resources, we have a 32 characters limit. If the identifier length exceeds this number after compression, we remove the middle part and replace it for a hash made up from the string itself. |
| 135 | + |
| 136 | +## Contributing |
| 137 | +We would love for you to contribute to [bitovi/github-actions-deploy-docker-to-ec2](https://github.com/bitovi/github-actions-deploy-docker-to-ec2). |
| 138 | +Would you like to see additional features? [Create an issue](https://github.com/bitovi/github-actions-deploy-docker-to-ec2/issues/new) or a [Pull Requests](https://github.com/bitovi/github-actions-deploy-docker-to-ec2/pulls). We love discussing solutions! |
| 139 | + |
| 140 | +## License |
| 141 | +The scripts and documentation in this project are released under the [MIT License](https://github.com/bitovi/github-actions-deploy-docker-to-ec2/blob/main/LICENSE). |
0 commit comments