How do you self-host Next.js across multiple instances (cache handlers, ISR, build IDs)?

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  output: "standalone", // self-contained server for the container image

  // ISR pages, Route Handler responses and fetch cache entries go to a shared store,
  // not to each instance's disk and memory.
  cacheHandler: require.resolve("./cache-handler.mjs"),
  cacheMaxMemorySize: 0, // no per-instance in-memory copy that could go stale

  // Version skew protection: ?dpl= on assets, x-deployment-id on navigations,
  // hard reload when a client meets a different deployment.
  deploymentId: process.env.DEPLOYMENT_VERSION,
};

export default nextConfig;

// cache-handler.mjs (referenced from next.config.ts)
// Lab stand-in for Redis: every instance reads and writes the same directory.
import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
import { createHash } from "node:crypto";
import { join } from "node:path";
import { serialize, deserialize } from "node:v8"; // keeps Buffer and Map values intact

const DIR = process.env.SHARED_CACHE_DIR ?? "/tmp/next-shared-cache";
mkdirSync(DIR, { recursive: true });
const file = (key) => join(DIR, createHash("sha256").update(key).digest("hex"));
const TAGS = join(DIR, "tags.json");
const readTags = () => (existsSync(TAGS) ? JSON.parse(readFileSync(TAGS, "utf8")) : {});

export default class SharedCacheHandler {
  async get(key) {
    const f = file(key);
    if (!existsSync(f)) return null;
    const entry = deserialize(readFileSync(f));
    const tags = [...(entry.tags ?? []), ...String(entry.value?.headers?.["x-next-cache-tags"] ?? "").split(",").filter(Boolean)];
    const revalidated = readTags();
    if (tags.some((t) => (revalidated[t] ?? 0) > entry.lastModified)) return null; // invalidated elsewhere
    return entry;
  }
  async set(key, data, ctx) {
    console.log(`[cache ${process.env.INSTANCE}] set ${key}`);
    writeFileSync(file(key), serialize({ value: data, lastModified: Date.now(), tags: ctx?.tags ?? [] }));
  }
  async revalidateTag(tags) {
    const all = readTags();
    for (const t of [tags].flat()) all[t] = Date.now();
    writeFileSync(TAGS, JSON.stringify(all));
    console.log(`[cache ${process.env.INSTANCE}] revalidateTag ${JSON.stringify(tags)}`);
  }
  resetRequestCache() {}
}

# 1. Build ONCE in CI. Pin the Server Functions key so a rebuild of the same
#    release keeps decrypting closures created by the previous one.
export NEXT_SERVER_ACTIONS_ENCRYPTION_KEY="$(vault read -field=key secret/next-actions)"  # openssl rand -base64 32, stored once
export DEPLOYMENT_VERSION="$(git rev-parse --short HEAD)"
next build
docker build -t registry.example.com/shop:"$DEPLOYMENT_VERSION" .

# 2. Run the SAME image on every instance (never `next build` per container).
#    All instances share the cache store and the deployment id.
docker run -e INSTANCE=a -e REDIS_URL=redis://cache:6379 -p 3000:3000 registry.example.com/shop:"$DEPLOYMENT_VERSION"
docker run -e INSTANCE=b -e REDIS_URL=redis://cache:6379 -p 3001:3000 registry.example.com/shop:"$DEPLOYMENT_VERSION"

# 3. Behind nginx: disable buffering for streaming, and drain on shutdown
#    (send SIGTERM and wait 10-30 s so in-flight requests and after() callbacks finish).