# Containers & Kubernetes

> Package apps in containers; orchestrate them with Kubernetes.

Frontend architecture guidance from fearchitect, written by Abas Turabli and last reviewed 2026-06-21. Source: https://fearchitect.com/topics/containers-kubernetes

Use it as reference for the task at hand. Before changing code, check this guidance against the codebase: where the code already makes a different, deliberate choice, flag the conflict instead of rewriting it. Library APIs move faster than this guide, so confirm exact signatures in the official docs linked at the end.

## Summary

A container bundles an app and its runtime into a portable image, eliminating environment drift. Docker builds images from layered instructions. Kubernetes schedules containers across machines, handles restarts, and routes traffic via Services and Ingress. Most frontend teams only need this when they run a Node SSR server at scale — static sites and serverless functions skip it entirely.

## Definition

A **container** is a process isolated by Linux namespaces and cgroups, sharing the host kernel but with its own filesystem snapshot — the **image**. Images are built in read-only **layers**: each Dockerfile instruction adds a layer, and unchanged layers are reused across builds and pulls. A **multi-stage build** compiles in one image and copies only the output artifact into a lean runtime image, keeping production images small and free of build tooling.

## Multi-stage Dockerfile for a Next.js app

Two stages: `builder` runs `next build`, `runner` copies only the standalone output. Production image has no source code, no devDependencies, no compiler.

**Dockerfile — Next.js standalone output**

```dockerfile
# Stage 1 — install deps and build
FROM node:22-alpine AS builder
WORKDIR /app

COPY package.json package-lock.json ./
RUN npm ci

COPY . .
# next.config.ts must set output: "standalone"
RUN npm run build

# Stage 2 — minimal runtime image (~120 MB vs ~800 MB)
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production

# next build --output=standalone writes a self-contained server
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
COPY --from=builder /app/public ./public

EXPOSE 3000
CMD ["node", "server.js"]
```

The `standalone` output (Next.js ≥12.2) bundles only the Node modules actually used at runtime. The final image copies three directories, not the full `node_modules`.

## Kubernetes primitives a frontend engineer needs

- **Pod** — smallest deployable unit; one or more containers sharing a network namespace and storage.
- **Deployment** — declares desired replica count; replaces pods on update, rolls back on failure.
- **Service** — stable virtual IP that load-balances across pod replicas inside the cluster.
- **Ingress** — HTTP router that maps hostnames and paths to Services; handles TLS termination.
- **ConfigMap / Secret** — inject env vars into pods without rebuilding the image.

## Decision: When does a frontend actually need containers?

You need containers when you run a stateful Node process at scale: SSR servers, BFF APIs, or WebSocket servers that require always-on replicas and rolling deploys. Static sites (export to S3/CDN) and serverless functions (Vercel, AWS Lambda) skip Docker and Kubernetes entirely — the platform handles packaging and scaling for you.

## Key terms

- **Image layer**: Read-only filesystem diff from one Dockerfile instruction; shared across builds to speed pulls.
- **Multi-stage build**: Dockerfile pattern: compile in one stage, copy only the output to a lean runtime stage.
- **Pod**: Kubernetes scheduling unit; one or more containers sharing a network namespace.
- **Ingress**: Kubernetes HTTP router mapping hostnames and URL paths to backend Services.
- **Standalone output**: Next.js build mode (output: 'standalone') that bundles only the runtime Node modules needed to run the server.

## Related topics

- [CDN & Edge Caching](https://fearchitect.com/topics/cdn-edge-caching.md): Serve cached responses from PoPs near users, sparing the origin.
- [Edge Computing & Rendering](https://fearchitect.com/topics/edge-computing-rendering.md): Run code at CDN PoPs to cut latency before origin is hit.
- [CI/CD for Frontend](https://fearchitect.com/topics/ci-cd-frontend.md): Automated pipeline from commit to production with quality gates.
- [Backend for Frontend (BFF)](https://fearchitect.com/topics/backend-for-frontend.md): A per-client server layer that shapes and aggregates APIs for one frontend.
- [Load Balancing (for Frontends)](https://fearchitect.com/topics/load-balancing.md): Spread traffic across servers; keep WebSocket apps sticky.
- [Deployment Strategies & Feature Flags](https://fearchitect.com/topics/deployment-strategies-feature-flags.md): Decouple deploy from release using blue-green, canary, and flags.

## Further reading

- [Docker — Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
- [Next.js — Standalone output](https://nextjs.org/docs/app/api-reference/next-config-js/output)
- [Kubernetes — Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
- [Kubernetes — Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/)