twelve-factor

Twelve-Factor App

The Twelve-Factor App methodology provides architectural guidelines for building portable, resilient software-as-a-service applications optimized for modern cloud platforms and container runtimes.

When to Use

• Cloud-Native Application Architecture: Designing stateless, scalable web applications intended for Kubernetes, PaaS, or container clusters.
• Legacy Replatforming: Modernizing monolithic legacy software into containerized, cloud-ready deployment units.
• Zero-Downtime Rolling Deploys: Ensuring services can boot fast, survive sudden terminations, and run alongside differing versions.
• Standardizing Microservice Conventions: Establishing uniform configuration, logging, and dependency isolation standards across teams.

Quick Start

# Dockerfile embodies dependencies, port binding, and build/run separation
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json .
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
# Dependencies
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
# Config via Env
ENV PORT=8080
# Port Binding
EXPOSE 8080
# Disposability (Process 1)
CMD ["node", "dist/main.js"]

Core Concepts

Declarative Dependencies & Port Binding

Dependencies are strictly pinned; applications self-host their web servers and bind directly to assigned ports:

// Explicit pinned dependencies in package.json
{
  "dependencies": {
    "express": "4.19.2",
    "pg": "8.12.0"
  }
}

// Self-contained port binding (no external application container like Tomcat required)
const port = process.env.PORT || 8080;
app.listen(port, () => console.log(`Server bound to port ${port}`));

Config Stored in the Environment

Strict separation of code and config; credentials, hostnames, and secrets are injected via environment variables:

// Validate environment config with Zod at startup
import { z } from "zod";

const EnvSchema = z.object({
  PORT: z.coerce.number().default(8080),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url(),
  NODE_ENV: z.enum(["development", "test", "production"]).default("production"),
});

export const config = EnvSchema.parse(process.env);