DEV Community: Simone Lusenti

Hosting a Next.js (App Router) app on Amazon S3

Simone Lusenti — Wed, 23 Oct 2024 20:49:53 +0000

In this tutorial, we'll walk through the steps to deploy a Next.js App Router app on Amazon S3. We'll start by creating and properly configuring an S3 bucket with its CloudFront distribution, then we'll configure Next.js to export a static build. In a future tutorial, we'll explore how to create a deployment pipeline for automatic deployments on every git push, using AWS CodePipeline.

(This website is built with Next.js 15 App Router, exported to a static build, and hosted on Amazon S3.)

Prerequisites

You need an AWS account; there is no charge for the resources we'll create, but you'll be billed for usage when exceeding the free tier limits. To complete the tutorial, you'll need a custom domain (registered on Amazon Route 53 or any other DNS provider) and an ACM certificate associated with it; see the AWS documentation for more information on how to obtain a certificate.
You will also need the AWS CLI installed and configured with your credentials. See the AWS CLI documentation for more information, and AWS CLI SSO configuration if you need help setting up your account.
This tutorial is for Next.js 14, Next.js 15 and assumes you're using the App Router. If you don't have a Next.js App Router project, you can create one by running npx create-next-app@latest. When prompted, always choose the default suggested options.

Since Amazon S3 can only host static contents, we will start by understanding what a static site is and which features are supported.

Understanding what's a static site

A static site is a website where the code is generated at build time. This means that the HTML is generated before the user requests it, and the same HTML is served for every request (i.e, it doesn't need to be generated on-demand based on cookies, user sessions, etc.).

Things you can have in a static site:

Client components, including useState, animations, and everything you could do with old vanilla React 18 / Next.js 13
Client components performing client-side network requests (e.g. fetch data from an external API)
Server components that can be generated at build time (e.g. a blog post page that fetches the post content from a CMS when deploying)

When you run next build to generate a static export, Server Components consumed inside the app directory will run during the build, similar to traditional static-site generation. The resulting component will be rendered into static HTML for the initial page load and a static payload for client navigation between routes.

Things that are not supported when exporting to a static site:

Dynamic routes (there's a way to make dynamic routes work, see next.js docs for generateStaticParams)
Cookies, headers
Middleware, Rewrites, Redirects
Server actions

Now that you have decided if you can go with a static site, let's start by creating the infrastructure!

Infrastructure overview

We'll create the following resources on AWS; in another tutorial, we'll see how to create this infrastructure with Infrastructure-as-Code using AWS CDK. For now, let's see how to do it manually.

Here's an outline of what each service will do:

Amazon CloudFront: The CDN that will serve our static files. Using CloudFront will allow us to use a custom domain name and configure an SSL certificate to serve our site over HTTPS.
Amazon S3: The storage service that will host our static files. We'll need to enable S3 Static Website Hosting so that our files are served as a website (i.e. index.html is served when you navigate to the root URL, and subfolders are served as well).
AWS Certificate Manager (ACM): The service to request and manage our SSL/TLS certificates.
Amazon Route 53: The DNS service that will route our custom domain name to our CloudFront distribution.
AWS CodePipeline: The service to create a pipeline that will automatically deploy our changes to S3 when we push to our Git repository.

Update the Next.js configuration

We need to update the Next.js configuration to export a static build, and to build it in a way that is compatible with S3 Static Website Hosting.

Locate your next.config.js (or next.config.mjs, next.config.ts) file and add the following properties:

{
    // ... existing configuration

    images: {
        // Disable Next.js optimizations for images (it's not available for static sites
        // and will throw an error)
        unoptimized: true,
    },

    // This tells Next.js to export a static build to the `out` folder
    output: "export",

    // This tells Next.js to export pages as "folders with an `index.html` file inside"
    // We use this option so we can avoid having the `.html` extension at the end of the page URLs.
    trailingSlash: true,
}

Try running next build and see if it works. Errors are generally self-explanatory, but if you have any issues, please review the checklist above ("Things that are not supported when exporting to a static site").

If the build succeeds, you should see a new folder called out with the static build of your site. It will contain the index.html file for each page, as well as any other assets like images, stylesheets, and all the js files.

Create the infrastructure

Create the S3 bucket

Navigate to the S3 console, click on Create bucket, and fill in the following fields:

Region: Select the region you want to host your site in (it doesn't really matter since we'll be using CloudFront to serve the files from the closest edge location). You can change the region from the top-right dropdown.
Bucket name: Your domain name (e.g. allthingsserverless.com); this doesn't really matter, actually, you can name it whatever you want.
Object ownership: Leave it as ACLs disabled.
Block all public access: Uncheck this box - your website will need to be public.
Acknowledge the warning about the bucket public access.
Click on Create bucket.

Enable static website hosting

The next step is to enable static website hosting for the bucket. This setting is required so that S3 knows how to serve the files as a website (i.e. index.html is served when you navigate to the root URL, and subfolders are served as well).

Once the bucket is created, click on it to open the bucket settings page, then:

Enter the Properties tab.
Scroll down to the bottom of the page and find the Static website hosting section.
Choose Edit
Check the Enable box under Static website hosting
Confirm Hosting type is set to Host a static website
In Index document, enter index.html
In Error document, enter index.html
Click on Save changes

Allow public read access to the bucket contents

We now need to allow public read access to the bucket contents so that CloudFront can serve the files via the Website Hosting feature.

Go back to the bucket settings page, click on the Permissions tab, and find the Bucket policy section.
Click on Edit
Replace the content of the policy with the following:

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": "*",
        "Action": "s3:GetObject",
        "Resource": "arn:aws:s3:::your-domain-name/*"
    }]
}

Make sure to replace your-domain-name with your actual domain name or bucket name; don't remove the /* at the end as we need it to allow access to all objects in the bucket
Click on Save changes

Create the CloudFront distribution

Navigate to the CloudFront console (Option+S, CloudFront), click on Create distribution, and fill in the following fields:

As Origin domain, select the bucket we created in the previous step.
A warning will tell you you should use the website endpoint; accept the warning by clicking on Use website endpoint

Find the Viewer protocol policy section, and set it to Redirect HTTP to HTTPS to make sure your site is only served over HTTPS
Scroll down to the Web Application Firewall (WAF) section, and select Do not enable security protections; we don't need them for our simple static site
Before confirming the distribution creation, continue to the next paragraph.

Attach a custom domain

Find the Settings section towards the bottom of the page:

Under Alternate domain name (CNAME), press Add item and enter your domain name (e.g. allthingsserverless.com)
Repeat the process for the Alternate domain name (CNAME) section, this time entering www.allthingsserverless.com (with the www prefix)
Select the SSL certificate. Only certificates compatible with your domain name will be shown in the dropdown. If you don't have a certificate, see these instructions on obtaining one.
Optionally enable HTTP/3
Click on Create distribution

Take note of the Distribution ID; we'll need it later, it's a string like E3QEPN1YNJOOW8.

Creating the distribution will take approximately 5 minutes. While waiting for it to be created, you can continue to the next section. Until then, you will see a DNS resolution error.

Update the DNS settings

If you're using Route 53, follow these instructions:

Navigate to the Route 53 console, click on Hosted zones, and select your domain name.
Click on the Create record button.
Set the record type to A.
Check the Alias option.
In the Route traffic to field, select Alias to a CloudFront distribution.
From the Choose distribution dropdown, select the distribution we need to connect our domain name to. Only distributions with a compatible custom domain name will be shown in the dropdown.
Click on Create records.

If you're not using Route 53:

Please refer to your DNS provider's documentation for more information. You probably need to create a CNAME record having the DNS name of the CloudFront distribution as its target/value. You can find the DNS name of the distribution in the CloudFront console, under the Distribution Settings section.

Upload the static files to S3

Now that we have created the infrastructure and configured our Next.js 15 static site, we need to upload it.

For this tutorial, we'll use a simple script to upload the static files to S3 and invalidate the CloudFront cache. In a later tutorial, we'll see how to create a deployment pipeline for automatic deployments on every git push, using AWS CodePipeline.

You'll need the AWS Command Line Interface. Install the AWS CLI if you don't have it already by following the Installing the AWS CLI v2 guide. You also need to configure the AWS CLI with your credentials; this depends on how your AWS account and organization is set up. I acknowledge IAM can be quite complex to set up, especially if you're not used to it, so I recommend you follow this comprehensive guide by AWS: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html.

Once you have the AWS CLI installed and configured, create the following script (I name it deploy.sh):

#! /bin/bash -e

# Build (next static)
pnpm run build

# Copy to S3
aws s3 sync ./out s3://YOUR-DOMAIN-NAME --delete

# Invalidate CloudFront cache
aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID_COPIED_FROM_PREVIOUS_STEP --paths "/*"

Here's an explanation of what each command does:

pnpm run build: Runs next build to generate the static files
aws s3 sync ./out s3://YOUR-DOMAIN-NAME --delete: Copies the static files to the S3 bucket, deleting any files that no longer exist in the out folder
aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID_COPIED_FROM_PREVIOUS_STEP --paths "/*": Invalidates the CloudFront cache so that the new files are served (optional)

Now make the file executable by running chmod +x deploy.sh.
You can deploy your changes by running ./deploy.sh.

Your changes will be published within a few seconds.
You can run the script again to publish a new version every time you make changes to your site.

Conclusion

You did it! You are now hosting a Next.js 15 App Router static site on Amazon S3.
It's fully serverless:

it will cost you nothing if no one visits your site
it will cost you a few cents per month if your site gets visitors
never goes down

Remember S3 charges for Storage, Requests and Data Transfer, and CloudFront charges for Requests and Data Transfer. You can use the AWS Calculator to estimate your costs once your free tier usage is exceeded.

Part 1 - Deploying a PHP (Laravel) application to Amazon ECS

Simone Lusenti — Sat, 19 Oct 2024 08:09:53 +0000

In this first part of our tutorial series, we'll walk through the steps to deploy a PHP (Laravel) application to Amazon ECS. We'll start by creating a Docker image, pushing it to Amazon ECR, creating an ECS Task Definition, an ECS Cluster, an ECS Service and connecting a domain name to the service.

Working with Docker and ECR

Create a Dockerfile, and nginx config

In the root of your git repo, create a Dockerfile with the following contents:

# Use the official PHP-FPM image as the base
FROM public.ecr.aws/docker/library/php:fpm

# Define a user variable
ARG user=www-data

# Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \
    git curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip unzip libzip-dev \
    nginx \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && docker-php-ext-install \
        pdo_mysql \
        mbstring \
        exif \
        pcntl \
        bcmath \
        gd \
        zip

# Install Composer
COPY --from=public.ecr.aws/composer/composer:latest-bin /usr/bin/composer /usr/bin/composer

# Create a system user for running Composer and Artisan commands
RUN mkdir -p /home/$user/.composer && \
    chown -R $user:$user /home/$user

# Copy Nginx configuration and entrypoint script
COPY ./docker/default.conf /etc/nginx/sites-enabled/default
COPY ./docker/entrypoint.sh /etc/entrypoint.sh

# Make the entrypoint script executable
RUN chmod +x /etc/entrypoint.sh

# Set the working directory
WORKDIR /var/www

# Copy the application code
COPY --chown=www-data:www-data . /var/www

# Install PHP dependencies
RUN composer install

# Expose port 80
EXPOSE 80

# Define the entrypoint
ENTRYPOINT ["/etc/entrypoint.sh"]

Create a new folder named docker and place the following two files inside.

docker/entrypoint.sh

#!/usr/bin/env bash

# Start Nginx service
service nginx start

# Run Laravel migrations
php artisan migrate --force

# Create symbolic link for storage
php artisan storage:link

# Clear and optimize the application cache
php artisan optimize:clear
php artisan optimize

# Start PHP-FPM
php-fpm

docker/default.conf

server {
    listen 80 default_server;
    index index.php index.html;
    server_name localhost;
    error_log  /var/log/nginx/error.log;
    access_log /var/log/nginx/access.log;
    root /var/www/public;

    location ~ \.php$ {
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass 127.0.0.1:9000;
        fastcgi_index index.php;

        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_param PATH_INFO $fastcgi_path_info;
        fastcgi_hide_header X-Powered-By;

        # Tells PHP we're using a reverse proxy with TLS termination
        fastcgi_param HTTPS on;
        fastcgi_param HTTP_X_FORWARDED_PROTO $scheme;
        fastcgi_param HTTP_X_FORWARDED_SSL on;
        add_header Content-Security-Policy "upgrade-insecure-requests" always;
    }

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}

And make entrypoint.sh executable by running chmod +x docker/entrypoint.sh.

Pushing the image to Amazon ECR

The first step is to push the image to ECR. You need to perform this step manually first, before you can go ahead and deploy the application to ECS.

Create an ECR repository

Create an ECR repository by heading over to the Amazon ECR console, clicking Create repository, and typing in a repository name. For this example, we'll use demo-app.

Once created, copy the URI of the repository. You will need this URI later.

Push the image to ECR

Select the repository you just created, click on View push commands, and run the commands in your terminal. The commands will look like this (make sure to select the correct region and use the correct Account ID):

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
docker build -t demo-app .
docker tag demo-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/demo-app:latest
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/demo-app:latest

Once the commands are successfully run, go back to the Amazon ECR console, enter the repository, and confirm that the image has been pushed successfully with the tag latest.

Working with Amazon ECS

Create an ECS Task Definition

The next step is to create an ECS Task Definition with the Docker image we just pushed to ECR.
Start by heading over to the Amazon ECS console, under Task Definitions, click Create new task definition.

Chose a unique name for the task definition (we'll use demo-app), and make sure Fargate is selected as the launch type. Don't change anything else in this section for now.

Scroll down to the Container - 1 section, and type in the following values:

Name: demo-app
Image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/demo-app:latest (replace with your own ECR URI we copied earlier)

Later, you'll probably want to adjust the memory and CPU settings depending on your application. You can also add Environment Variables and EFS Volumes here, if you need to. We'll cover it in a separate tutorial.

Don't change anything else in this section for now. Scroll down to the bottom and click Create.

Create an ECS Cluster

We now need to create an ECS Cluster. The cluster is where we'll run the service defined in the task definition we just created.

Head over to the Amazon ECS console, under Clusters, click Create cluster, type a cluster name, and make sure to select AWS Fargate (serverless) as infrastructure:

The cluster will take a couple of minutes to create. The cluster creation can occasionally fail, especially on new accounts; just wait a few minutes and try again, choosing a different cluster name.

Create an ECS Service

Open the cluster you just created, scroll down to the Services table, click Create, and type in the following values:

Family: demo-app
Revision: 1 (leave this as is)
Service name: demo-app

Do not click Create yet.

Add a Load Balancer

Since we're probably serving the application over HTTPS, we'll want to add a load balancer. You cannot do this later.

Scroll down to the Networking section, and select a VPC you want to deploy the service to. Make sure the VPC has a Public Subnet with an Internet Gateway attached to it. If you don't have a VPC, you can create one by clicking Create a new VPC and following the wizard.

Once you have selected a VPC, continue reading.

Scroll down to the Load balancing section, select Application Load Balancer, and select the option Create a new load balancer.

If this option is not available, you probably didn't select a VPC in the previous step.

Adjust the following values:

Load balancer name: demo-app-alb
Health check grace period: 300 (I recommend setting this to 300 seconds, which is 5 minutes, to allow your app to start and stabilize)

Under the Listener section, keep the Create a new listener option selected, but adjust the values to use port 443, and the HTTPS protocol. To confirm this selection, you'll need an ACM certificate for the domain you want to use; see the AWS documentation for more information on how to obtain one.

Under the Target group section, adjust the following values:

Protocol: HTTP (it's the default, make sure to keep it since our nginx container is listening on port 80)
Deregistration delay: 60 (I recommend to set this to 60 seconds instead of the default 5 minutes to make deployments a bit faster)
Health check path: / (I recommend to set this to a route, such as /healthcheck, you specifically create in your app; you can leave it as default for now)

Click Create.

Check the Service Status

Services may take a few minutes to show up in the Services table. Just wait a bit and refresh the page if you don't see the new service right away.

If everything went well, you should see the service listed in the Services table, with a status of Active and Deployments and tasks showing 1/1 running task.

Deployment errors are shown like this:

To debug deployment errors, open the service, then click on the Deployments tab; scroll down to the Events section, and click on the most recently started task's Id. The Logs section of the task execution will show you more details about what went wrong.

Laravel usually complains about an incomplete storage folder structure (e.g., missing one of framework, cache, sessions). We'll see how to attach an EFS volume to the task definition to fix this in a separate tutorial.

Connect a domain name to the service

You probably want to connect a domain name to the service we just deployed. In the previous steps, we already created an Application Load Balancer, which is the AWS component responsible for routing internet traffic to the service.

We also already provisioned an ACM certificate, which is used to encrypt traffic between the end-users and the load balancer.

To complete the process and make your application accessible over HTTPS from the public internet, you need to create a DNS record that points your domain name to the load balancer. This process is different depending on which DNS provider you're using; please refer to their documentation for more information.

Start by obtaining the Application Load Balancer's DNS name. Navigate to the Search bar in the AWS Console (Option+S on macOS), type Load Balancer, and select Load Balancers (EC2 Feature). You'll see a table with the Load Balancer we need to connect our domain name to:

Copy the DNS name of the load balancer.

If you're using Route 53, follow these instructions:

Navigate to the Route 53 console, click on Hosted zones, and select your domain name.
Click on the Create record button.
Set the record type to A.
Check the Alias option.
In the Route traffic to field, select Alias to Application and Classic Load Balancer, and choose the region of the load balancer.
From the Choose load balancer dropdown, select the load balancer we need to connect our domain name to. If you have multiple load balancers, check the one you select from the dropdown must match the DNS name of the load balancer we copied earlier.
Turn off Evaluate Target Health.
Click on Create records.

If you're not using Route 53:

Please refer to your DNS provider's documentation for more information. You probably need to create a CNAME record having the DNS name of the load balancer as its target/value.

Congratulations

Once you have created the DNS record, wait a few minutes for it to propagate, and then try to access your application through the domain name.

Congratulations! You have now successfully deployed a PHP (Laravel) application to AWS ECS.

Coming soon in this tutorial series

Attaching an EFS volume to the task definition to fix Laravel's storage folder structure issue
Using AWS CodePipeline to automatically deploy new code to the service
Automating infrastructure provisioning with AWS CDK