This guide covers deploying your Next.js website built with Agility CMS to AWS using Amazon Elastic Container Service (ECS) with either EC2 instances or AWS Fargate. This approach provides full control over your infrastructure and supports all Next.js features including Server-Side Rendering (SSR), API routes, and Incremental Static Regeneration (ISR). ## Overview AWS ECS is a fully managed container orchestration service that allows you to run Docker containers at scale. You can deploy Next.js applications using either: - **AWS Fargate** (Recommended) - Serverless compute for containers, no EC2 instances to manage - **EC2 Launch Type** - More control over underlying infrastructure, requires EC2 instance management ### Benefits of Deploying to AWS ECS - ✅ **Full Next.js Feature Support** - Supports Static Site Generation (SSG), Server-Side Rendering (SSR), Incremental Static Regeneration (ISR), API routes, and React Server Components - ✅ **Scalability** - Auto-scaling capabilities to handle traffic spikes - ✅ **High Availability** - Multi-AZ deployment for fault tolerance - ✅ **Load Balancing** - Application Load Balancer (ALB) for traffic distribution - ✅ **Container Orchestration** - Managed container deployment and updates - ✅ **Cost Control** - Pay only for resources you use - ✅ **Security** - Integration with AWS IAM, VPC, and security groups ### Starting Point Most developers deploying Agility CMS websites to AWS ECS will be starting from an existing Next.js project: - **Agility CMS Next.js Starter** - [https://github.com/agility/agilitycms-nextjs-starter](https://github.com/agility/agilitycms-nextjs-starter) - Production-ready starter with App Router, TypeScript, and Tailwind CSS - **Agility CMS Comprehensive Demo** - [https://github.com/agility/nextjs-demo-site-2025](https://github.com/agility/nextjs-demo-site-2025) - Full-featured demo with AI search, internationalization, and advanced features - **Your Own Agility Next.js Site** - Existing project already integrated with Agility CMS These starters already include proper Next.js configuration, Agility CMS integration, and the necessary build scripts. You'll still need to configure your environment variables and Docker setup. ## Prerequisites Before you begin, ensure you have: 1. **AWS Account** - Sign up at [aws.amazon.com](https://aws.amazon.com) if you don't have one 2. **AWS CLI** - Installed and configured with appropriate credentials 3. **Docker** - Installed locally for building container images 4. **Agility CMS Instance** - With API credentials (see below if you need to set one up) 5. **Node.js 18.x or later** - For local development and testing 6. **Basic AWS Knowledge** - Familiarity with ECS, ECR, VPC, and IAM concepts ### Get Your Agility CMS Credentials If you don't already have an Agility CMS instance set up: 1. **Sign up for Agility CMS** - Create a free account at [agilitycms.com](https://agilitycms.com) 2. **Create an Instance** - Create a new instance (you can start with a Blog Starter template) 3. **Get API Keys** - Navigate to **Settings > API Keys** in your Agility CMS dashboard 4. **Copy your credentials**: - `GUID` (Instance ID) - `Live API Key` (for production) - `Preview API Key` (for development/preview) - `Security Key` (for webhooks) You'll need these credentials for both local development and AWS ECS deployment configuration. ## Deployment Architecture The recommended architecture for deploying Next.js to AWS ECS includes: ``` Internet ↓ Application Load Balancer (ALB) ↓ ECS Service (Fargate or EC2) ↓ Next.js Container (Port 3000) ↓ Agility CMS API ``` **Components:** - **Application Load Balancer (ALB)** - Routes traffic to ECS tasks, handles SSL termination - **ECS Cluster** - Manages container instances - **ECS Service** - Maintains desired number of running tasks - **Task Definition** - Defines container configuration, environment variables, and resources - **Amazon ECR** - Stores Docker container images - **VPC** - Isolated network environment for your resources ## Step 1: Prepare Your Next.js Project ### Verify Build Scripts Ensure your `package.json` has the required scripts: ```json { "scripts": { "dev": "next dev", "build": "next build", "start": "next start" } } ``` **Note**: The Agility CMS Next.js starters already include proper Next.js configuration for containerized deployment. ### Next.js Component Considerations Before deploying, ensure your Next.js application is compatible with containerized deployment: 1. **Image Component - Use AgilityPic (Required)**: > **⚠️ IMPORTANT**: Do NOT use `next/image` for Agility CMS images. Use the `AgilityPic` component from `@agility/nextjs` instead. AgilityPic is a simple wrapper around the standard `

Deploying Next.js to AWS EC2