
subaud is authored by Court Schuett (he/him). While Court is an 8090 Inc employee, opinions and statements on this blog are his own.


Court Schuett


# Next.js SSR App Runner Deployment with CloudFront

This project demonstrates how to deploy a Next.js SSR application using AWS App Runner and CloudFront. It uses an AWS CDK to define and deploy the infrastructure. The project is managed with projen and includes several custom tasks to support the development process.

Update to: https://subaud.io/blog/next-js-app-runner-with-deployment

GitHub: https://github.com/schuettc/next-js-app-runner-deployment

## Architecture

The architecture consists of the following components:

- Next.js application
- AWS App Runner to host and run the Next.js application
- Amazon CloudFront as a content delivery network (CDN) in front of App Runner
- Lambda@Edge to rewrite headers and support dynamic routing
- Route53 ARecords for DNS
- AWS CDK to define and deploy the infrastructure
- GitHub actions for CI/CD

![Overview](/images/blog/updated-nextjs-app-runner-deployment-with-srr/NextJSAppCloudfront.png)

## Prerequisites

- AWS Account
- Node.js (version 18 or later)
- AWS CDK CLI
- Docker (for local development and testing)

## Getting Started

Clone the repository:

```bash
git clone https://github.com/schuettc/next-js-app-runner-deployment.git
cd next-js-app-runner-deployment
```

Install dependencies:

```bash
yarn
```

Deploy the stack:

```bash
yarn launch
```

## Project Structure

- `src/`: Contains the CDK infrastructure code
  - `appRunner.ts`: Defines the App Runner service
  - `cloudfront.ts`: Sets up the CloudFront distribution
  - `lambda.ts`: Creates the Lambda@Edge function
  - `route53.ts`: Defines the DNS records
  - `next-js-app-runner-deployment.ts`: Main stack definition
- `src/resources/app/`: Contains the Next.js application code

## Custom Origin Request Policy

This project implements a custom origin request policy for CloudFront, which is required when using App Runner as the origin. The policy allows specific headers to be forwarded to the origin:

```typescript:src/cloudfront.ts
    const customOriginRequestPolicy = new OriginRequestPolicy(
      this,
      'UserAgentRefererHeadersPolicy',
      {
        headerBehavior: OriginRequestHeaderBehavior.allowList(
          'User-Agent',
          'Referer',
        ),
      },
    );
```

This custom policy ensures that the `User-Agent` and `Referer` headers are forwarded to the App Runner service, which solves the 404 error that occurs when using AppRunner as the origin for a CloudFront distribution.

https://docs.aws.amazon.com/apprunner/latest/dg/request-route-404-troubleshoot.html

## Lambda@Edge for Header Rewriting

This project uses a Lambda@Edge function to rewrite headers, which is crucial for supporting dynamic routing in Next.js when using App Runner behind CloudFront. The function is associated with both the Origin Request and Viewer Request events in CloudFront.

Here's the Lambda@Edge function code:

```typescript:src/resources/lambdaEdge/index.ts
import { CloudFrontRequestEvent, CloudFrontRequestResult } from 'aws-lambda';

export const handler = async (
  event: CloudFrontRequestEvent,
): Promise<CloudFrontRequestResult> => {
  const request = event.Records[0].cf.request;
  const origin = request.origin?.custom;

  if (origin && origin.domainName) {
    request.headers.host = [{ key: 'Host', value: origin.domainName }];
  }

  return request;
};

```

This function rewrites the `Host` header to match the origin's domain name, ensuring that App Runner receives the correct host information. This is essential for Next.js to properly handle dynamic routes.

The Lambda@Edge function is associated with CloudFront in the following way:

```typescript
        edgeLambdas: [
          {
            functionVersion: lambdaEdgeFunction.function.currentVersion,
            eventType: LambdaEdgeEventType.ORIGIN_REQUEST,
          },
          {
            functionVersion: lambdaEdgeFunction.function.currentVersion,
            eventType: LambdaEdgeEventType.VIEWER_REQUEST,
          },
        ],
      },
```

By attaching this function to both the Origin Request and Viewer Request events, we ensure that the headers are properly rewritten for all incoming requests, allowing Next.js to handle dynamic routing correctly when deployed on App Runner behind CloudFront.

## Deployment

The project includes a GitHub Actions workflow for automated deployments. When you push changes to the `main` branch, it will automatically deploy the updated stack to AWS.

To deploy manually:

1. Configure your AWS credentials
2. Run `yarn deploy`

### projen configuration

```typescript
const deploy = project.github?.addWorkflow("deploy");
deploy?.on({
  push: {
    branches: ["main"],
  },
  workflow_dispatch: {},
});

deploy?.addJobs({
  deploy: {
    runsOn: ["ubuntu-latest"],
    permissions: {
      contents: JobPermission.READ,
      id_token: JobPermission.WRITE,
    },
    steps: [
      { uses: "actions/checkout@v4" },
      {
        uses: "actions/setup-node@v4",
        with: {
          "node-version": "18",
        },
      },
      { run: "yarn install --frozen-lockfile" },
      {
        uses: "aws-actions/configure-aws-credentials@v4",
        with: {
          "aws-access-key-id": "${{ secrets.AWS_ACCESS_KEY_ID }}",
          "aws-secret-access-key": "${{ secrets.AWS_SECRET_ACCESS_KEY }}",
          "aws-region": "${{ secrets.AWS_REGION }}",
        },
      },
      { run: "npx cdk deploy --require-approval never" },
    ],
  },
});
```

## Server Side Rendering

This NextJS includes support for Server Side Rendering (SRR) through dynamic routes and API routes:

```typescript
export default function Post({ params }: { params: { id: string } }) {
  return (
    <div>
      <h1>Post {params.id}</h1>
      <p>This is a dynamic route for post with ID: {params.id}</p>
    </div>
  );
}
```

```typescript
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Hello from the API!" });
}

export async function POST(request: Request) {
  const body = await request.json();
  return NextResponse.json({ message: "Hello from the API!", data: body });
}
```

## Local Development

To run the Next.js application locally:

Navigate to the app directory:

```bash
cd src/resources/app
```

Install dependencies:

```bash
yarn
```

Start the development server:

```bash
yarn dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser

## GitHub Updates with Projen

The project uses projen to manage the project and the Next.js application. We have replaced the default projen upgrade with a custom upgrade. This allows us to upgrade the dependencies for both the main project and the Next.js application in a single step.

```typescript
const upgradeWorkflow = project.github?.addWorkflow("upgrade");
upgradeWorkflow?.on({
  schedule: [{ cron: "0 0 * * 1" }],
  workflow_dispatch: {},
});

upgradeWorkflow?.addJobs({
  upgrade: {
    runsOn: ["ubuntu-latest"],
    permissions: {
      contents: JobPermission.WRITE,
      pullRequests: JobPermission.WRITE,
    },
    steps: [
      { uses: "actions/checkout@v4" },
      { uses: "actions/setup-node@v4", with: { "node-version": "18" } },
      { run: "yarn install" },
      { run: "npx projen upgrade:projen" },
      { run: "npx projen upgrade:nextjs" },
      {
        name: "Create Pull Request",
        uses: "peter-evans/create-pull-request@v6",
        with: {
          token: "${{ secrets.PROJEN_GITHUB_TOKEN }}",
          "commit-message": "chore: upgrade dependencies",
          branch: "projen-upgrade",
          title: "chore: upgrade dependencies",
          body: "This PR upgrades project dependencies, including projen and Next.js. Auto-generated by projen upgrade workflow.",
        },
      },
    ],
  },
});

project.addTask("upgrade:nextjs", {
  exec: ["cd src/resources/app", "yarn upgrade --latest", "cd ../../.."].join(
    " && "
  ),
});

project.addTask("upgrade:projen", {
  description: "Upgrade projen dependencies",
  steps: [
    { exec: "yarn upgrade projen @projen/awscdk-app-ts" },
    { exec: "npx projen" },
  ],
});
```

## Route 53 DNS Configuration

This project uses Amazon Route 53 to manage DNS records for the deployed application. The `Route53Resources` construct in `src/route53.ts` sets up the necessary DNS records to point your domain to the CloudFront distribution.

Two A records are created:

- One for the apex domain (e.g., example.com)
- One for the www subdomain (e.g., www.example.com)

Both A records are set up as alias records pointing to the CloudFront distribution:

```typescript
new ARecord(this, "AliasRecord", {
  zone: hostedZone,
  target: RecordTarget.fromAlias(new CloudFrontTarget(props.distribution)),
  recordName: `${props.domainName}.`,
});

new ARecord(this, "WWWAliasRecord", {
  zone: hostedZone,
  target: RecordTarget.fromAlias(new CloudFrontTarget(props.distribution)),
  recordName: `www.${props.domainName}.`,
});
```

This configuration ensures that both the apex domain and the www subdomain resolve to the CloudFront distribution, which in turn serves the Next.js application running on App Runner.

By using alias records, we benefit from Route 53's ability to automatically update the DNS records if the CloudFront distribution's domain name changes, without any manual intervention.

Make sure to update your domain's name servers to use the ones provided by your Route 53 hosted zone for this configuration to take effect.


Updated NextJS App deployed to App Runner with SSR and GitHub Actions


# Next.js App Runner Deployment with CloudFront

This project demonstrates how to deploy a Next.js application using AWS App Runner and CloudFront. It uses the AWS CDK to define and deploy the infrastructure. The project is managed with projen and includes several custom tasks to support the development process.

Please see update: [https://subaud.io/blog/updated-nextjs-app-runner-deployment-with-ssr](https://subaud.io/blog/updated-nextjs-app-runner-deployment-with-ssr)

## Architecture

The architecture consists of the following components:

1. A Next.js application
2. AWS App Runner to host and run the Next.js application
3. Amazon CloudFront as a content delivery network (CDN) in front of App Runner
4. AWS CDK to define and deploy the infrastructure

## Key Features

- Serverless deployment of a Next.js application using AWS App Runner
- CloudFront distribution with custom origin request policy
- Automated CI/CD pipeline using GitHub Actions
- Infrastructure as Code using AWS CDK

## Prerequisites

- AWS Account
- Node.js (version 18 or later)
- AWS CDK CLI
- Docker (for local development and testing)

## Getting Started

Clone the repository:

```bash
git clone https://github.com/schuettc/next-js-app-runner-deployment.git
cd next-js-app-runner-deployment
```

Install dependencies:

```bash
yarn
```

Deploy the stack:

```bash
yarn launch
```

## Project Structure

- `src/`: Contains the CDK infrastructure code
  - `appRunner.ts`: Defines the App Runner service
  - `cloudfront.ts`: Sets up the CloudFront distribution
  - `next-js-app-runner-deployment.ts`: Main stack definition
- `src/resources/app/`: Contains the Next.js application code

## Custom Origin Request Policy

This project implements a custom origin request policy for CloudFront, which is required when using App Runner as the origin. The policy allows specific headers to be forwarded to the origin:

```typescript:src/cloudfront.ts
    const customOriginRequestPolicy = new OriginRequestPolicy(
      this,
      'UserAgentRefererHeadersPolicy',
      {
        headerBehavior: OriginRequestHeaderBehavior.allowList(
          'User-Agent',
          'Referer',
        ),
      },
    );
```

This custom policy ensures that the `User-Agent` and `Referer` headers are forwarded to the App Runner service, which solves the 404 error that occurs when using AppRunner as the origin for a CloudFront distribution.

https://docs.aws.amazon.com/apprunner/latest/dg/request-route-404-troubleshoot.html

## Deployment

The project includes a GitHub Actions workflow for automated deployments. When you push changes to the `main` branch, it will automatically deploy the updated stack to AWS.

To deploy manually:

1. Configure your AWS credentials
2. Run `yarn deploy`

### projen configuration

```typescript
const deploy = project.github?.addWorkflow('deploy');
deploy?.on({
  push: {
    branches: ['main'],
  },
  workflow_dispatch: {},
});

deploy?.addJobs({
  deploy: {
    runsOn: ['ubuntu-latest'],
    permissions: {
      contents: JobPermission.READ,
      id_token: JobPermission.WRITE,
    },
    steps: [
      { uses: 'actions/checkout@v4' },
      {
        uses: 'actions/setup-node@v4',
        with: {
          'node-version': '18',
        },
      },
      { run: 'yarn install --frozen-lockfile' },
      {
        uses: 'aws-actions/configure-aws-credentials@v4',
        with: {
          'aws-access-key-id': '${{ secrets.AWS_ACCESS_KEY_ID }}',
          'aws-secret-access-key': '${{ secrets.AWS_SECRET_ACCESS_KEY }}',
          'aws-region': '${{ secrets.AWS_REGION }}',
        },
      },
      { run: 'npx cdk deploy --require-approval never' },
    ],
  },
});
```

## Local Development

To run the Next.js application locally:

Navigate to the app directory:

```bash
cd src/resources/app
```

Install dependencies:

```bash
yarn
```

Start the development server:

```bash
yarn dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser

## GitHub Updates with Projen

The project uses projen to manage the project and the Next.js application. We have replaced the default projen upgrade with a custom upgrade. This allows us to upgrade the dependencies for both the main project and the Next.js application in a single step.

```typescript
const upgradeWorkflow = project.github?.addWorkflow('upgrade');
upgradeWorkflow?.on({
  schedule: [{ cron: '0 0 * * 1' }],
  workflow_dispatch: {},
});

upgradeWorkflow?.addJobs({
  upgrade: {
    runsOn: ['ubuntu-latest'],
    permissions: {
      contents: JobPermission.WRITE,
      pullRequests: JobPermission.WRITE,
    },
    steps: [
      { uses: 'actions/checkout@v4' },
      { uses: 'actions/setup-node@v4', with: { 'node-version': '18' } },
      { run: 'yarn install' },
      { run: 'npx projen upgrade:projen' },
      { run: 'npx projen upgrade:nextjs' },
      {
        name: 'Create Pull Request',
        uses: 'peter-evans/create-pull-request@v6',
        with: {
          'token': '${{ secrets.PROJEN_GITHUB_TOKEN }}',
          'commit-message': 'chore: upgrade dependencies',
          'branch': 'projen-upgrade',
          'title': 'chore: upgrade dependencies',
          'body':
            'This PR upgrades project dependencies, including projen and Next.js. Auto-generated by projen upgrade workflow.',
        },
      },
    ],
  },
});

project.addTask('upgrade:nextjs', {
  exec: ['cd src/resources/app', 'yarn upgrade --latest', 'cd ../../..'].join(
    ' && ',
  ),
});

project.addTask('upgrade:projen', {
  description: 'Upgrade projen dependencies',
  steps: [
    { exec: 'yarn upgrade projen @projen/awscdk-app-ts' },
    { exec: 'npx projen' },
  ],
});
```


NextJS App deployed to App Runner with GitHub Actions


In this demo we'll see how to deploy a NextJS application to AWS App Runner via CDK using GitHub Actions. This demo will combine and showcase several useful tools to help with deployments. Much of this could also be done using a CDK Pipeline. For smaller and simpler use cases, this can be a lighter weight way of doing it, but is more fragile. This is a simpler and cheaper version the previous [CDK Pipeline for ECS hosted NextJS App](https://subaud.io/blog/cdk-pipeline-ecs-hosted-nextjs) while still supporting the main features in it.

GitHub: https://github.com/schuettc/cdk-nextjs-apprunner

## Overview

![Overview](/images/blog/nextjs-app-deployed-to-app-runner-with-cdk/Overview.png)

The core of this demo is the mechanism to take a local [NextJS](https://nextjs.org/) app, upload it to an S3 bucket, build it using Docker and deploy it to [AWS App Runner](https://aws.amazon.com/apprunner/). By using [AWS CodePipeline](https://aws.amazon.com/codepipeline/) and [AWS CodeBuild](https://aws.amazon.com/codebuild/) to build the [Docker](https://www.docker.com/) image, we eliminate the need to have Docker running locally for our deployment. This allows us to use GitHub actions to use CDK to deploy this application.

## Uploading to S3

```typescript
const dockerAsset = new Asset(this, 'DockerAsset', {
  path: './site',
  exclude: ['**/node_modules/**', '**/lib/**', '/**/.next/**'],
  ignoreMode: IgnoreMode.GIT,
});
```

By using [Asset](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.Asset.html) we are able to Zip and upload all of the relevant files in our NextJS application to an S3 bucket managed by CDK. We will use this S3 bucket as the trigger for our CodePipeline.

## CodePipeline

The actual pipeline for this demo is relatively simple. Using polling on the S3 bucket, it will download the Zip file from S3, extract the files, and execute a build on them.

```typescript
this.pipeline = new Pipeline(this, 'Pipeline', {
  stages: [
    {
      stageName: 'Source',
      actions: [
        new S3SourceAction({
          actionName: 'S3Source',
          bucket: dockerAsset.bucket,
          bucketKey: dockerAsset.s3ObjectKey,
          output: sourceOutput,
        }),
      ],
    },
    {
      stageName: 'Build',
      actions: [
        new CodeBuildAction({
          actionName: 'DockerBuild',
          project: codeBuildProject,
          input: sourceOutput,
          outputs: [buildOutput],
        }),
      ],
    },
  ],
});
```

The buildSpec for this involves three basic steps:

1. Log in to ECR
2. Execute `docker build`
3. Execute `docker push`

```typescript
buildSpec: BuildSpec.fromObject({
  version: '0.2',
  phases: {
    pre_build: {
      commands: [
        'echo Logging in to Amazon ECR...',
        'aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com',
      ],
    },
    build: {
      commands: [
        'echo Build started on `date`',
        'echo Building the Docker image...',
        'docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .',
        'docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG',
      ],
    },
    post_build: {
      commands: [
        'echo Build completed on `date`',
        'echo Pushing the Docker image...',
        'docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG',
      ],
    },
  },
}),
```

With these three steps, we are able to create a Docker image and push to our [Amazon ECR repository](https://docs.aws.amazon.com/ecr/). This is what will be consumed by our App Runner service.

## ImageChecker

In order to make sure the Docker image has been created and is available for the App Runner service, we will create a Lambda backed Custom Resource that will periodically check the pipeline to ensure it has completed successfully. When it has, the Customer Resource will complete and the CDK can continue. We can enforce this by adding a dependency to the Customer Resource to the App Runner service.

```typescript
appRunnerService.service.node.addDependency(imageChecker);
```

Now the CDK will not start deploying the App Runner service until the Customer Resource has completed. This will only run on the initial build. On updates, when a new image is pushed to ECR after the build process completes, App Runner will automatically deploy the updated image.

## App Runner

Finally, we will create the App Runner service and automatically deploy the image.

```typescript
this.service = new apprunnerAlpha.Service(this, 'Service', {
  source: apprunnerAlpha.Source.fromEcr({
    imageConfiguration: { port: 3000 },
    repository: ecrRepository.repository,
    tagOrDigest: 'latest',
  }),
  autoDeploymentsEnabled: true,
  accessRole: appRunnerRole,
});
```

To ensure this works correctly with NextJS we will add a `HOSTNAME` environment variable to the App Runner service.

```typescript
this.service.addEnvironmentVariable('HOSTNAME', '0.0.0.0');
```

## Projen

To help manage this project, we will be using [projen](https://projen.io/).

### Subproject

In addition to the main project, we are also using a subproject to manage the NextJS application with a `parent` of the main project.

```typescript
const site = new web.NextJsTypeScriptProject({
  parent: project,
  defaultReleaseBranch: 'main',
  name: 'cdk-nextjs-apprunner-site',
  outdir: 'site',
  projenrcTs: true,
  tailwind: false,
  tsconfig: {
    compilerOptions: {
      rootDir: '.',
      baseUrl: '.',
    },
    include: [
      'pages/**/*.ts',
      'pages/**/*.tsx',
      'components/**/*.ts',
      'components/**/*.tsx',
      '**/*.ts',
      '**/*.tsx',
      'next-env.d.ts',
    ],
    exclude: ['node_modules'],
  },
  deps: ['@cloudscape-design/components', '@cloudscape-design/global-styles'],
});

site.synth();
```

### CDK Deploy GitHub Action

Because we are using CodeBuild to build the Docker image, we can use GitHub actions to start the deploy process. To do this with projen, we will create a new workflow. This will be added to the existing actions and trigger on a merge or push to `main`.

```typescript
const cdkDeploy = project.github.addWorkflow('cdk-deploy');
cdkDeploy.on({
  push: { branches: ['main'] },
  pullRequest: { branches: ['main'], types: ['closed'] },
});

cdkDeploy.addJobs({
  deploy: {
    runsOn: ['ubuntu-latest'],
    name: 'Deploy CDK Stack',
    permissions: {
      actions: JobPermission.WRITE,
      contents: JobPermission.READ,
      idToken: JobPermission.WRITE,
    },
    if: "github.event.pull_request.merged == true || github.event_name == 'push'",
    steps: [
      { uses: 'actions/checkout@v3' },
      {
        name: 'Setup Node.js',
        uses: 'actions/setup-node@v3',
        with: {
          'node-version': '18',
        },
      },
      { run: 'yarn install --frozen-lockfile' },
      {
        name: 'Configure AWS Credentials',
        uses: 'aws-actions/configure-aws-credentials@v4',
        with: {
          'aws-access-key-id': '${{ secrets.AWS_ACCESS_KEY_ID }}',
          'aws-secret-access-key': '${{ secrets.AWS_SECRET_ACCESS_KEY }}',
          'aws-region': 'us-east-1',
          'role-session-name': 'GitHubActionsCDKDeploy',
        },
      },
      {
        name: 'CDK Diff',
        run: 'npx cdk diff',
      },
      {
        name: 'CDK Deploy',
        run: 'npx cdk deploy --all --require-approval never',
      },
    ],
  },
});
```

### AWS Credentials

In order to use this feature, you will need to create a user in your AWS account that has sufficient permissions to deploy the CDK. Using the ACCESS_KEY_ID and SECRET_ACCESS_KEY generated for this user, GitHub can deploy the CDK. To create a user with permissions you can run:

```bash
./setup_aws_cdk_deploy
```

The output will contain an ACCESS_KEY_ID and SECRET_ACCESS_KEY that can be added to your GitHub repo as secrets.

![GitHubSecrets](/images/blog/nextjs-app-deployed-to-app-runner-with-cdk/GitHubSecrets.png)

The policy attached to this user has extensive permissions so care must be taken with this ACCESS_KEY_ID.


Deploy a NextJS Application to AWS App Runner using CDK

NextJS App deployed to App Runner with CDK


# CDK Pipeline for ECS hosted NextJS App

In this demo we will explore and see how to use two different, but complementary techniques:

- Using CDK Pipelines to deploy a Stack
- Deploying a NextJS application to an ECS Fargate container

In each of these examples, we will look at several different mechanisms to provide security and scaling. This blog has been converted to using this method of hosting.

## GitHub Repo

https://github.com/schuettc/cdk-pipeline-ecs-hosted-nextjs

## CDK Pipeline

![CDKPipelineOverview](/images/blog/cdk-pipeline-ecs-hosted-nextjs/CDKPipelineOverview.png)

This demo uses [AWS CodeStar Connections](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html) to create a link to a GitHub repo. This will allow us to use GitHub commits to push changes to our NextJS App through the CDK Pipeline.

The [cdk-pipeline-ecs-hosted-nextjs.ts](https://github.com/schuettc/cdk-pipeline-ecs-hosted-nextjs/blob/main/src/cdk-pipeline-ecs-hosted-nextjs.ts) file will create a Stack with a self-mutating CodePipeline. This is the Pipeline contains a Stage that will deploy the the NextJSApp Stack. This Pipeline is triggered by the GitHub repo and branch associated.

```typescript
const pipeline = new CodePipeline(this, 'Pipeline', {
  synth: new CodeBuildStep('Synth', {
    input: CodePipelineSource.connection(props.githubRepo, props.githubBranch, {
      connectionArn: props.connectionArn,
    }),
    commands: ['yarn install --frozen-lockfile', 'yarn build', 'npx cdk synth'],
    rolePolicyStatements: [
      new PolicyStatement({
        actions: ['sts:AssumeRole'],
        resources: ['*'],
        conditions: {
          StringEquals: {
            'iam:ResourceTag/aws-cdk:bootstrap-role': 'lookup',
          },
        },
      }),
    ],
  }),
  selfMutation: true,
  dockerEnabledForSynth: true,
});

pipeline.addStage(
  new NextJSAppStage(this, 'NextJSApp', props as NextJSAppProps),
);
```

## NextJS App

![NextJSAppOverview](/images/blog/cdk-pipeline-ecs-hosted-nextjs/ECSFargateNextJSApp.png)

The demo optionally uses a pre-configured Route 53 Hosted Zone domain. Otherwise the traffic will route through the following services:

- Route 53 (Optional)
- Cloudfront
- Application Load Balancer
- Fargate with Auto Scaling Group

### Securing Traffic

In order to ensure that traffic uses this path, we will establish the follow security mechanisms.

#### Fargate

```typescript
const fargateTargetGroup = new ApplicationTargetGroup(
  this,
  'nextJsAppTargetGroup',
  {
    vpc: props.vpc,
    port: 3000,
    protocol: ApplicationProtocol.HTTP,
    targets: [this.fargateService],
    healthCheck: {
      path: '/',
      protocol: Protocol.HTTP,
      port: '3000',
    },
  },
);
```

When configuring the `ApplicationTargetGroup` that points to the Fargate application, a Security Group will be created that allows traffic from the Application Load Balancer to access the Fargate task.

![FargateSecurityGroup](/images/blog/cdk-pipeline-ecs-hosted-nextjs/FargateSecurityGroup.png)

This Security Group will use the Security Group of the Application Load Balancer.

### Application Load Balancer

```typescript
this.applicationLoadBalancerSecurityGroup.addIngressRule(
  Peer.anyIpv4(),
  Port.tcp(80),
);
```

This Security Group will allow traffic in from any IPv4 address on TCP Port 80. In order to ensure that traffic from sources besides Cloudfront are rejected, we will use a configuration of the Listener.

```typescript
const fargateListener = this.applicationLoadBalancer.addListener(
  'fargateListener',
  {
    port: 80,
    protocol: ApplicationProtocol.HTTP,
    open: true,
    defaultAction: ListenerAction.fixedResponse(403),
  },
);

fargateListener.addAction('ForwardFromCloudFront', {
  action: ListenerAction.forward([fargateTargetGroup]),
  conditions: [
    ListenerCondition.httpHeader(props.customHeader, [props.randomString]),
  ],
  priority: 1,
});
```

This Listener will by default reject all traffic that is sent to it. An additional action will be used to allow traffic with a specific header and value to forward to the Fargate application. This information is created separately and configured during deployment. For more information on this mechanism, see [building-a-websocket-server-with-fargate-and-cdk](https://subaud.io/blog/building-a-websocket-server-with-fargate-and-cdk).

The result:

![Listener](/images/blog/cdk-pipeline-ecs-hosted-nextjs/Listener.png)

### Cloudfront

```typescript
this.distribution = new Distribution(this, 'CloudfrontDistribution', {
  minimumProtocolVersion: SecurityPolicyProtocol.TLS_V1_2_2021,
  defaultBehavior: {
    origin: new LoadBalancerV2Origin(props.applicationLoadBalancer, {
      httpPort: 80,
      protocolPolicy: OriginProtocolPolicy.HTTP_ONLY,
      originId: 'default-origin',
    }),
    viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    cachePolicy: CachePolicy.CACHING_DISABLED,
    allowedMethods: AllowedMethods.ALLOW_GET_HEAD_OPTIONS,
    originRequestPolicy: OriginRequestPolicy.ALL_VIEWER,
  },
  domainNames: props.domainName ? [props.domainName] : undefined,
  certificate: certificate,
  priceClass: PriceClass.PRICE_CLASS_100,
});
```

The Distribution created includes a domain and SSL certificate to provide HTTPS access to the Fargate task. Requests to HTTP will redirect to HTTPS.

#### Domain (optional)

```typescript
if (props.domainName) {
  hostedZone = HostedZone.fromLookup(this, 'HostedZone', {
    domainName: props.domainName,
  });

  certificate = new Certificate(this, 'Certificate', {
    domainName: props.domainName,
    validation: CertificateValidation.fromDns(hostedZone),
  });
}

if (hostedZone && props.domainName) {
  new AaaaRecord(this, 'mainAaaaRecord', {
    zone: hostedZone,
    target: RecordTarget.fromAlias(new CloudFrontTarget(this.distribution)),
  });

  new ARecord(this, 'mainARecord', {
    zone: hostedZone,
    target: RecordTarget.fromAlias(new CloudFrontTarget(this.distribution)),
  });
}
```

If a domain is included in the deployment, a certificate will be created and used in addition to the default Cloudfront certificate. DNS records will be created associated with this domain.

#### Custom Header

To create the header used to ensure traffic is sourced from Cloudfront, the Cloudfront Distribution Origin will be configured to send it using a Custom Resource.

```typescript
new CustomResource(this, 'customHeaderCustomResource', {
  serviceToken: customHeaderCustomResourceProvider.serviceToken,
  properties: {
    DistributionId: this.distribution.distributionId,
    Origins: [
      {
        OriginId: 'default-origin',
        CustomHeaders: [
          {
            HeaderName: props.customHeader,
            HeaderValue: props.randomString,
          },
        ],
      },
    ],
  },
});
```

The result will look something like this:

![Origin](/images/blog/cdk-pipeline-ecs-hosted-nextjs/Origin.png)

### Fargate Task

```typescript
const ecsTask = new FargateTaskDefinition(this, 'ecsTask', {
  memoryLimitMiB: 2048,
  cpu: 1024,
  runtimePlatform: {
    operatingSystemFamily: OperatingSystemFamily.LINUX,
    cpuArchitecture: CpuArchitecture.X86_64,
  },
});

ecsTask.addContainer('NextJsContainer', {
  image: ContainerImage.fromAsset('nextjs-docker'),
  containerName: 'nextJsApp',
  portMappings: [{ containerPort: 3000, hostPort: 3000 }],
  logging: LogDrivers.awsLogs({
    streamPrefix: 'nextJsApp',
  }),
  environment: {},
});

const taskSecurityGroup = new SecurityGroup(this, 'taskSecurityGroups', {
  vpc: props.vpc,
});

this.fargateService = new FargateService(this, 'nextJsAppFargateService', {
  cluster: cluster,
  taskDefinition: ecsTask,
  assignPublicIp: true,
  desiredCount: 1,
  vpcSubnets: { subnetType: SubnetType.PUBLIC },
  securityGroups: [taskSecurityGroup],
});
```

The Fargate Service will be configured with a port mapping for port 3000. This corresponds to the Application Load Balancer that forwards traffic to port 3000. The Fargate task will be deployed in the VPC created during the deployment and assigned a public IP address.

The Docker image used is the example shown here: https://github.com/vercel/next.js/tree/canary/examples/with-docker

### Result

The result is an Application Load Balancer that will only accept traffic with a specific header and value. This header and value are known only by the deployed Cloudfront Distribution. Traffic with this header will be forwarded to a Fargate task that only allows traffic from the Security Group associated with the Application Load Balancer. This deployment allows us to restrict access to the the Fargate task that uses the Cloudfront Distribution.

## Configuration and Deployment

To deploy this repo, you will need to complete the following steps:

1. Fork this repo
2. Configure Codestar connections with your GitHub repo
3. Configure a Hosted Zone in Route 53 with your domain (optional)
4. Configure your `.env` file
5. Deploy

### Configure Codestar

To configure your AWS account to support a connection to GitHub, follow the instructions here: https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html

The result will look something like this:

![Connections](/images/blog/cdk-pipeline-ecs-hosted-nextjs/Connections.png)

### Configure Hosted Zone (optional)

To create a Hosted Zone, follow the instructions here: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html

The result will look something like this:

![HostedZone](/images/blog/cdk-pipeline-ecs-hosted-nextjs/HostedZone.png)

### Configure `.env` file

Before deploying, you will need to configure a `.env` file with the following fields:

```bash
CONNECTION_ARN=arn:aws:codestar-connections:us-east-1:112233445566:connection/XXXXXXXXXXXXXXXXXXXXXXXX
GITHUB_REPO=XXXXXXXXXXX/cdk-pipeline-ecs-hosted-nextjs
GITHUB_BRANCH=main
DOMAIN_NAME=example.com
```

`DOMAIN_NAME` is optional

### Deploy

To deploy the Pipeline:

```bash
yarn launch
```

Deploying the Pipeline will begin the process of deploying the NextJSApp stack.


A CDK Pipeline example that will deploy a NextJS App on ECS

Nextjs

Updated NextJS App deployed to App Runner with SSR and GitHub Actions

NextJS App deployed to App Runner with GitHub Actions

NextJS App deployed to App Runner with CDK

CDK Pipeline for ECS hosted NextJS App