--- # Terraform Next.js module for AWS  A zero-config Terraform module for self-hosting Next.js sites serverless on AWS Lambda. ## Features Some features are still under development, here is a list of features that are currently supported and what we plan to bring with the next releases: - ✅ Supports any version of [Next.js](https://nextjs.org/) - ✅ [Terraform](https://www.terraform.io/) `v0.15+` - ✅ Unlimited parallel deployments of Next.js apps (atomic deployments) - ✅ Static, SSG, Lambda and API pages (with [dynamic routes](https://nextjs.org/docs/routing/dynamic-routes)) - ✅ Automatic expiration of old static assets - ✅ [Rewrites](https://nextjs.org/docs/api-reference/next.config.js/rewrites) & [Redirects](https://nextjs.org/docs/api-reference/next.config.js/redirects) - ✅ [Image Component & Image Optimization](https://nextjs.org/docs/basic-features/image-optimization) support - 🚧 [Incremental Static Regeneration](https://nextjs.org/docs/basic-features/data-fetching#incremental-static-regeneration) - ⛔️ [Middleware](https://nextjs.org/docs/advanced-features/middleware) (Not supported by Lambda@Edge / CloudFront functions) ## Architecture The Next.js Terraform module is designed as a full stack AWS app. It relies on multiple AWS services and connects them to work as a single application:  ## Usage ### Prerequisites You should have the following tools installed: - [Terraform](https://www.terraform.io/downloads) - [Node.js](https://nodejs.org) - [Bash](https://www.gnu.org/software/bash/) & [curl](https://curl.se/) (Should be available by default on many Linux based images or macOS) > **Note:** Additionally we assume here that you already have a public [Route53 Hosted Zone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html) associated with your AWS account. > > This is a requirement in the preview phase of atomic deployments, where each deployment gets a unique subdomain assigned. > It will change once atomic deployments become generally available. ### Setup the Next.js Terraform module The Terraform module contains the system that is later used for creating new deployments and managing the aliases (domains) for your Next.js app(s). Creating the Terraform stack is only required on initial setup and creates the global resources (CloudFront distributions, DynamoDB tables, S3 storage) that is used for handling incoming requests to your website. Create a new `main.tf` file in an empty folder (or add it to your existing Terraform stack) and add the following content: ```tf terraform { required_providers { aws = { source = "hashicorp/aws" version = "~> 4.0" } } } # Main region where the resources should be created in # Should be close to the location of your viewers provider "aws" { region = "us-west-2" } # Provider used for creating the Lambda@Edge function which must be deployed # to us-east-1 region (Should not be changed) provider "aws" { alias = "global_region" region = "us-east-1" } ########### # Variables ########### variable "custom_domain" { description = "Your custom domain" type = string default = "example.com" } # Assuming that the ZONE of your domain is already available in your AWS account (Route 53) # https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/AboutHZWorkingWith.html variable "custom_domain_zone_name" { description = "The Route53 zone name of the custom domain" type = string default = "example.com." } ######## # Locals ######## locals { # A wildcard domain(ex: *.example.com) has to be added when using atomic deployments: aliases = [var.custom_domain, "*.${var.custom_domain}"] } ####################### # Route53 Domain record ####################### # Get the hosted zone for the custom domain data "aws_route53_zone" "custom_domain_zone" { name = var.custom_domain_zone_name } # Create a new record in Route 53 for the domain resource "aws_route53_record" "cloudfront_alias_domain" { for_each = toset(local.aliases) zone_id = data.aws_route53_zone.custom_domain_zone.zone_id name = each.key type = "A" alias { name = module.tf_next.cloudfront_domain_name zone_id = module.tf_next.cloudfront_hosted_zone_id evaluate_target_health = false } } ########## # SSL Cert ########## # Creates a free SSL certificate for CloudFront distribution # For more options (e.g. multiple domains) see: # https://registry.terraform.io/modules/terraform-aws-modules/acm/aws/ module "cloudfront_cert" { source = "terraform-aws-modules/acm/aws" version = "~> 3.0" domain_name = var.custom_domain zone_id = data.aws_route53_zone.custom_domain_zone.zone_id subject_alternative_names = slice(local.aliases, 1, length(local.aliases)) wait_for_validation = true tags = { Name = "CloudFront ${var.custom_domain}" } # CloudFront works only with certs stored in us-east-1 providers = { aws = aws.global_region } } ########################## # Terraform Next.js Module ########################## module "tf_next" { source = "milliHQ/next-js/aws" version = "1.0.0-canary.4" cloudfront_aliases = local.aliases cloudfront_acm_certificate_arn = module.cloudfront_cert.acm_certificate_arn deployment_name = "atomic-deployments" enable_multiple_deployments = true multiple_deployments_base_domain = "*.${var.custom_domain}" providers = { aws.global_region = aws.global_region } } ######### # Outputs ######### output "api_endpoint" { value = module.tf_next.api_endpoint } output "api_endpoint_access_policy_arn" { value = module.tf_next.api_endpoint_access_policy_arn } ``` To create the resources in your AWS account, run the following commands: ```sh terraform init # Only needed on the first time running Terraform terraform plan # (Optional) See what resources Terraform will create terraform apply # Create the resources in your AWS account > Apply complete! > > Outputs: > > api_endpoint = "https://Note
The main branch currently contains the atomic deployments alpha preview.
For the lastest stable release, check out thev0.xbranch.Please see our blog post "The road to Atomic Deployments"
or watch the latest release review for more information:
[| no | | cloudfront\_create\_distribution | Controls whether the main CloudFront distribution should be created. | `bool` | `true` | no | | cloudfront\_external\_arn | When using an external CloudFront distribution provide its arn. | `string` | `null` | no | | cloudfront\_external\_id | When using an external CloudFront distribution provide its id. | `string` | `null` | no | | cloudfront\_minimum\_protocol\_version | The minimum version of the SSL protocol that you want CloudFront to use for HTTPS connections. One of SSLv3, TLSv1, TLSv1\_2016, TLSv1.1\_2016, TLSv1.2\_2018 or TLSv1.2\_2019. | `string` | `"TLSv1"` | no | | cloudfront\_origin\_request\_policy | Id of a custom request policy that overrides the default policy (AllViewer). Can be custom or managed. | `string` | `null` | no | | cloudfront\_price\_class | Price class for the CloudFront distributions (main & proxy config). One of PriceClass\_All, PriceClass\_200, PriceClass\_100. | `string` | `"PriceClass_100"` | no | | cloudfront\_response\_headers\_policy | Id of a response headers policy. Can be custom or managed. Default is empty. | `string` | `null` | no | | cloudfront\_webacl\_id | An optional webacl2 arn or webacl id to associate with the cloudfront distribution | `string` | `null` | no | | create\_image\_optimization | Controls whether resources for image optimization support should be created or not. | `bool` | `true` | no | | debug\_use\_local\_packages | Use locally built packages rather than download them from npm. | `bool` | `false` | no | | deployment\_name | Identifier for the deployment group (only lowercase alphanumeric characters and hyphens are allowed). | `string` | `"tf-next"` | no | | enable\_multiple\_deployments | Controls whether it should be possible to run multiple deployments in parallel (requires multiple\_deployments\_base\_domain). | `bool` | `false` | no | | image\_optimization\_lambda\_memory\_size | Amount of memory in MB the worker Lambda Function for image optimization can use. Valid value between 128 MB to 10,240 MB, in 1 MB increments. | `number` | `2048` | no | | lambda\_attach\_policy\_json | Whether to deploy additional lambda JSON policies. If false, lambda\_policy\_json will not be attached to the lambda function. (Necessary since policy strings are only known after apply when using Terraforms data.aws\_iam\_policy\_document) | `bool` | `false` | no | | lambda\_attach\_to\_vpc | Set to true if the Lambda functions should be attached to a VPC. Use this setting if VPC resources should be accessed by the Lambda functions. When setting this to true, use vpc\_security\_group\_ids and vpc\_subnet\_ids to specify the VPC networking. Note that attaching to a VPC would introduce a delay on to cold starts | `bool` | `false` | no | | lambda\_policy\_json | Additional policy document as JSON to attach to the Lambda Function role | `string` | `null` | no | | lambda\_role\_permissions\_boundary | ARN of IAM policy that scopes aws\_iam\_role access for the lambda | `string` | `null` | no | | multiple\_deployments\_base\_domain | Default wildcard domain where new deployments should be available. Should be in the form of *.example.com. | `string` | `null` | no | | tags | Tag metadata to label AWS resources that support tags. | `map(string)` | `{}` | no | | tags\_s3\_bucket | Tag metadata to label AWS S3 buckets. Overrides tags with the same name in input variable tags. | `map(string)` | `{}` | no | | vpc\_security\_group\_ids | The list of Security Group IDs to be used by the Lambda functions. lambda\_attach\_to\_vpc should be set to true for these to be applied. | `list(string)` | `[]` | no | | vpc\_subnet\_ids | The list of VPC subnet IDs to attach the Lambda functions. lambda\_attach\_to\_vpc should be set to true for these to be applied. | `list(string)` | `[]` | no | ## Outputs | Name | Description | |------|-------------| | api\_endpoint | API endpoint that is used by the CLI. | | api\_endpoint\_access\_policy\_arn | ARN of the policy that grants access to the API endpoint. | | cloudfront\_custom\_error\_response | Preconfigured custom error response the CloudFront distribution should use. | | cloudfront\_default\_cache\_behavior | Preconfigured default cache behavior the CloudFront distribution should use. | | cloudfront\_default\_root\_object | Preconfigured root object the CloudFront distribution should use. | | cloudfront\_domain\_name | Domain of the main CloudFront distribution (When created). | | cloudfront\_hosted\_zone\_id | Zone id of the main CloudFront distribution (When created). | | cloudfront\_ordered\_cache\_behaviors | Preconfigured ordered cache behaviors the CloudFront distribution should use. | | cloudfront\_origins | Preconfigured origins the CloudFront distribution should use. | | upload\_bucket\_id | n/a | ## Known issues Under the hood this module uses a lot of [Vercel's](https://github.com/vercel/vercel/) build pipeline. So issues that exist on Vercel are likely to occur on this project too. - Stack deletion (`terraform destroy`) fails on first run ([terraform-provider-aws#1721](https://github.com/hashicorp/terraform-provider-aws/issues/1721)) This is intentional because we cannot delete a Lambda@Edge function (Used by proxy module) in a synchronous way. It can take up to an hour for AWS to unbind a Lambda@Edge function from it's CloudFront distribution even when the distribution is already destroyed. **Workaround:** After running the initial `terraform destroy` command (that failed) wait ~1 hour and run the command again. This time it should run successfully and delete the rest of the stack. - Initial apply fails with error message `Error: error creating Lambda Event Source Mapping` ([#138](https://github.com/milliHQ/terraform-aws-next-js/issues/138)) There is some race condition when the permissions are created for the static deployment Lambda. This should only happen on the first deployment. **Workaround:** You should be able to run`terraform apply` again and the stack creation would proceed without this error. ## Contributing Contributions are welcome! If you want to improve this module, please take a look at our [contributing guidelines](https://github.com/milliHQ/terraform-aws-next-js/tree/main/CONTRIBUTING.md) to get started. ## About This project is maintained by [milliVolt infrastructure](https://milli.is). We build custom infrastructure solutions for any cloud provider. ## License Apache-2.0 - see [LICENSE](./LICENSE) for details. > **Note:** All sample projects in [`examples/*`](./examples) are licensed as MIT to comply with the official [Next.js examples](https://github.com/vercel/next.js/tree/canary/examples). ================================================ FILE: docker-compose.yml ================================================ ################################################################################ # This docker-compose file is only meant for e2e testing packages that # require an S3 / dynamoDB connection: # - test/routes.test.ts # - packages/deploy-trigger ################################################################################ version: '3.6' services: local-s3: image: minio/minio ports: - 9000:9000 command: server /data volumes: - s3-data:/data env_file: - ./test.env dynamodb-local: image: amazon/dynamodb-local:latest ports: - "8000:8000" volumes: s3-data: ================================================ FILE: docs/development.md ================================================ # Development This is a small guide to get started with development of this module. From time to time I come back to it as well when I forgot something. ## Testing For local testing make sure that you have the following tools installed on your machine: - [Docker](https://docs.docker.com/get-docker/) - [Docker Compose](https://docs.docker.com/compose/install/) (Already included in Docker for Mac & Windows) - [AWS SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) We have 2 kinds of tests: - **Unit tests** Unit tests have mostly no external requirements. However some of them (e.g. `deploy-trigger`) need a connection to external services like S3 which is emulated locally by docker containers. The unit tests are located at their corresponding packages. Before executing any unit tests, you should make sure to start the services from the workspace root: ```sh docker-compose up -d ``` - **e2e tests** The e2e tests ensure that real Next.js are bundled and deployed in the right way. To do this we have fixture apps in `/test/fixtures/` directory that are builded and then deployed locally in Docker containers via AWS SAM CLI. Running e2e tests consist of two steps: 1. Building the fixtures with `terraform-next-build`: ```sh yarn test:e2e:prepare ``` 2. Run the actual tests ```sh yarn test:e2e ``` ================================================ FILE: examples/.gitignore ================================================ *.lock.hcl ================================================ FILE: examples/atomic-deployments/.gitignore ================================================ # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. # dependencies /node_modules /.pnp .pnp.js # testing /coverage # next.js /.next/ /out/ # production /build # misc .DS_Store *.pem # debug npm-debug.log* yarn-debug.log* yarn-error.log* # local env files .env.local .env.development.local .env.test.local .env.production.local # vercel .vercel # Terraform **/.terraform/* *.tfstate *.tfstate.* # tf-next /.tf-next/ ================================================ FILE: examples/atomic-deployments/LICENSE ================================================ The MIT License (MIT) Copyright (c) 2022 Felix Haus (milliVolt infrastructure) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ FILE: examples/atomic-deployments/README.md ================================================ # Atomic Deployments Example This example shows how to use the atomic deployments feature with the [Next.js Terraform module for AWS](https://registry.terraform.io/modules/milliHQ/next-js/aws). To learn more about this feature, please see the blog post ["The road to Atomic Deployments"](https://milli.is/blog/the-road-to-atomic-deployments) or watch the release review: [First look at the new atomic deployments feature](https://youtu.be/NY3zKnIcLd4). ## Features - ✅ Unlimited parallel deployments of Next.js apps served by a single CloudFront distribution - ✅ Preview deployment subdomains, e.g. `
"Authorization"
]
"getServerSideProps" ran for "{initialPropsCounter}" times.
Counter: "{query.counter || 0}".
Server: {JSON.stringify(slug)}
Client: {JSON.stringify(query.slug)}
Params: {JSON.stringify(params)}
Query: {JSON.stringify(serverQuery)}
"getServerSideProps" ran for "{initialPropsCounter}" times.
Counter: "{query.counter || 0}".
Image Component
as a Background
This page demonstrates the usage of the{' '} next/image {' '} component with live examples.
This component is designed to{' '} automatically optimizate {' '} images on-demand as the browser requests them.
The layout property tells the image to respond differently
depending on the device size or the container size.
Select a layout below and try resizing the window or rotating your device to see how the image reacts.
The following is an example of a reference to an interal image from the{' '}
public directory.
This image is intentionally large so you have to scroll down to the next image.
The following is an example of a reference to an external image at{' '}
assets.vercel.com.
External domains must be configured in next.config.js using
the domains property.
You can optionally configure a cloud provider, device sizes, and more!
Checkout the{' '} Image Optimization documentation {' '} to learn more.
"getServerSideProps" ran for "{initialPropsCounter}" times.
Counter: "{query.counter || 0}".
| Primary Key | Attributes | ||||
|---|---|---|---|---|---|
| PK | GSI1SK | ||||
DEPLOYMENTS |
<CreateDate>#D#<DeploymentId> |
CreateDate | DeploymentAlias | DeploymentId | Status |
| Primary Key | Attributes | |||||
|---|---|---|---|---|---|---|
| GSI1PK | GSI1SK | |||||
D#<D-id> |
<CreateDate>#R#<hostnameRev>#<basePath> |
BasePath | CreateDate | DeploymentId | DeploymentAlias | HostnameRev |
Code: ${errorCode}
Code: ${errorCode}