1# Self-Hosting Next.js
2 
3Deploy Next.js outside of Vercel with confidence.
4 
5## Quick Start: Standalone Output
6 
7For Docker or any containerized deployment, use standalone output:
8 
9```js
10// next.config.js
11module.exports = {
12  output: 'standalone',
13};
14```
15 
16This creates a minimal `standalone` folder with only production dependencies:
17 
18```
19.next/
20├── standalone/
21│   ├── server.js          # Entry point
22│   ├── node_modules/      # Only production deps
23│   └── .next/             # Build output
24└── static/                # Must be copied separately
25```
26 
27## Docker Deployment
28 
29### Dockerfile
30 
31```dockerfile
32FROM node:20-alpine AS base
33 
34# Install dependencies
35FROM base AS deps
36WORKDIR /app
37COPY package.json package-lock.json* ./
38RUN npm ci
39 
40# Build
41FROM base AS builder
42WORKDIR /app
43COPY --from=deps /app/node_modules ./node_modules
44COPY . .
45RUN npm run build
46 
47# Production
48FROM base AS runner
49WORKDIR /app
50 
51ENV NODE_ENV=production
52 
53# Create non-root user
54RUN addgroup --system --gid 1001 nodejs
55RUN adduser --system --uid 1001 nextjs
56 
57# Copy standalone output
58COPY --from=builder /app/.next/standalone ./
59COPY --from=builder /app/.next/static ./.next/static
60COPY --from=builder /app/public ./public
61 
62USER nextjs
63 
64EXPOSE 3000
65ENV PORT=3000
66ENV HOSTNAME="0.0.0.0"
67 
68CMD ["node", "server.js"]
69```
70 
71### Docker Compose
72 
73```yaml
74version: '3.8'
75 
76services:
77  web:
78    build: .
79    ports:
80      - "3000:3000"
81    environment:
82      - NODE_ENV=production
83    restart: unless-stopped
84    healthcheck:
85      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/api/health"]
86      interval: 30s
87      timeout: 10s
88      retries: 3
89```
90 
91## PM2 Deployment
92 
93For traditional server deployments:
94 
95```js
96// ecosystem.config.js
97module.exports = {
98  apps: [{
99    name: 'nextjs',
100    script: '.next/standalone/server.js',
101    instances: 'max',
102    exec_mode: 'cluster',
103    env: {
104      NODE_ENV: 'production',
105      PORT: 3000,
106    },
107  }],
108};
109```
110 
111```bash
112npm run build
113pm2 start ecosystem.config.js
114```
115 
116## ISR and Cache Handlers
117 
118### The Problem
119 
120ISR (Incremental Static Regeneration) uses filesystem caching by default. This **breaks with multiple instances**:
121 
122- Instance A regenerates page → saves to its local disk
123- Instance B serves stale page → doesn't see Instance A's cache
124- Load balancer sends users to random instances → inconsistent content
125 
126### Solution: Custom Cache Handler
127 
128Next.js 14+ supports custom cache handlers for shared storage:
129 
130```js
131// next.config.js
132module.exports = {
133  cacheHandler: require.resolve('./cache-handler.js'),
134  cacheMaxMemorySize: 0, // Disable in-memory cache
135};
136```
137 
138#### Redis Cache Handler Example
139 
140```js
141// cache-handler.js
142const Redis = require('ioredis');
143 
144const redis = new Redis(process.env.REDIS_URL);
145const CACHE_PREFIX = 'nextjs:';
146 
147module.exports = class CacheHandler {
148  constructor(options) {
149    this.options = options;
150  }
151 
152  async get(key) {
153    const data = await redis.get(CACHE_PREFIX + key);
154    if (!data) return null;
155 
156    const parsed = JSON.parse(data);
157    return {
158      value: parsed.value,
159      lastModified: parsed.lastModified,
160    };
161  }
162 
163  async set(key, data, ctx) {
164    const cacheData = {
165      value: data,
166      lastModified: Date.now(),
167    };
168 
169    // Set TTL based on revalidate option
170    if (ctx?.revalidate) {
171      await redis.setex(
172        CACHE_PREFIX + key,
173        ctx.revalidate,
174        JSON.stringify(cacheData)
175      );
176    } else {
177      await redis.set(CACHE_PREFIX + key, JSON.stringify(cacheData));
178    }
179  }
180 
181  async revalidateTag(tags) {
182    // Implement tag-based invalidation
183    // This requires tracking which keys have which tags
184  }
185};
186```
187 
188#### S3 Cache Handler Example
189 
190```js
191// cache-handler.js
192const { S3Client, GetObjectCommand, PutObjectCommand } = require('@aws-sdk/client-s3');
193 
194const s3 = new S3Client({ region: process.env.AWS_REGION });
195const BUCKET = process.env.CACHE_BUCKET;
196 
197module.exports = class CacheHandler {
198  async get(key) {
199    try {
200      const response = await s3.send(new GetObjectCommand({
201        Bucket: BUCKET,
202        Key: `cache/${key}`,
203      }));
204      const body = await response.Body.transformToString();
205      return JSON.parse(body);
206    } catch (err) {
207      if (err.name === 'NoSuchKey') return null;
208      throw err;
209    }
210  }
211 
212  async set(key, data, ctx) {
213    await s3.send(new PutObjectCommand({
214      Bucket: BUCKET,
215      Key: `cache/${key}`,
216      Body: JSON.stringify({
217        value: data,
218        lastModified: Date.now(),
219      }),
220      ContentType: 'application/json',
221    }));
222  }
223};
224```
225 
226## What Works vs What Needs Setup
227 
228| Feature | Single Instance | Multi-Instance | Notes |
229|---------|----------------|----------------|-------|
230| SSR | Yes | Yes | No special setup |
231| SSG | Yes | Yes | Built at deploy time |
232| ISR | Yes | Needs cache handler | Filesystem cache breaks |
233| Image Optimization | Yes | Yes | CPU-intensive, consider CDN |
234| Middleware | Yes | Yes | Runs on Node.js |
235| Edge Runtime | Limited | Limited | Some features Node-only |
236| `revalidatePath/Tag` | Yes | Needs cache handler | Must share cache |
237| `next/font` | Yes | Yes | Fonts bundled at build |
238| Draft Mode | Yes | Yes | Cookie-based |
239 
240## Image Optimization
241 
242Next.js Image Optimization works out of the box but is CPU-intensive.
243 
244### Option 1: Built-in (Simple)
245 
246Works automatically, but consider:
247- Set `deviceSizes` and `imageSizes` in config to limit variants
248- Use `minimumCacheTTL` to reduce regeneration
249 
250```js
251// next.config.js
252module.exports = {
253  images: {
254    minimumCacheTTL: 60 * 60 * 24, // 24 hours
255    deviceSizes: [640, 750, 1080, 1920], // Limit sizes
256  },
257};
258```
259 
260### Option 2: External Loader (Recommended for Scale)
261 
262Offload to Cloudinary, Imgix, or similar:
263 
264```js
265// next.config.js
266module.exports = {
267  images: {
268    loader: 'custom',
269    loaderFile: './lib/image-loader.js',
270  },
271};
272```
273 
274```js
275// lib/image-loader.js
276export default function cloudinaryLoader({ src, width, quality }) {
277  const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`];
278  return `https://res.cloudinary.com/demo/image/upload/${params.join(',')}${src}`;
279}
280```
281 
282## Environment Variables
283 
284### Build-time vs Runtime
285 
286```js
287// Available at build time only (baked into bundle)
288NEXT_PUBLIC_API_URL=https://api.example.com
289 
290// Available at runtime (server-side only)
291DATABASE_URL=postgresql://...
292API_SECRET=...
293```
294 
295### Runtime Configuration
296 
297For truly dynamic config, don't use `NEXT_PUBLIC_*`. Instead:
298 
299```tsx
300// app/api/config/route.ts
301export async function GET() {
302  return Response.json({
303    apiUrl: process.env.API_URL,
304    features: process.env.FEATURES?.split(','),
305  });
306}
307```
308 
309## OpenNext: Serverless Without Vercel
310 
311[OpenNext](https://open-next.js.org/) adapts Next.js for AWS Lambda, Cloudflare Workers, etc.
312 
313```bash
314npx create-sst@latest
315# or
316npx @opennextjs/aws build
317```
318 
319Supports:
320- AWS Lambda + CloudFront
321- Cloudflare Workers
322- Netlify Functions
323- Deno Deploy
324 
325## Health Check Endpoint
326 
327Always include a health check for load balancers:
328 
329```tsx
330// app/api/health/route.ts
331export async function GET() {
332  try {
333    // Optional: check database connection
334    // await db.$queryRaw`SELECT 1`;
335 
336    return Response.json({ status: 'healthy' }, { status: 200 });
337  } catch (error) {
338    return Response.json({ status: 'unhealthy' }, { status: 503 });
339  }
340}
341```
342 
343## Pre-Deployment Checklist
344 
3451. **Build locally first**: `npm run build` - catch errors before deploy
3462. **Test standalone output**: `node .next/standalone/server.js`
3473. **Set `output: 'standalone'`** for Docker
3484. **Configure cache handler** for multi-instance ISR
3495. **Set `HOSTNAME="0.0.0.0"`** for containers
3506. **Copy `public/` and `.next/static/`** - not included in standalone
3517. **Add health check endpoint**
3528. **Test ISR revalidation** after deployment
3539. **Monitor memory usage** - Node.js defaults may need tuning
354 
355## Testing Cache Handler
356 
357**Critical**: Test your cache handler on every Next.js upgrade:
358 
359```bash
360# Start multiple instances
361PORT=3001 node .next/standalone/server.js &
362PORT=3002 node .next/standalone/server.js &
363 
364# Trigger ISR revalidation
365curl http://localhost:3001/api/revalidate?path=/posts
366 
367# Verify both instances see the update
368curl http://localhost:3001/posts
369curl http://localhost:3002/posts
370# Should return identical content
371```
372