Twelve-Factor Applications

The Twelve-Factor App is a methodology, published by Heroku engineers in 2011, for building software-as-a-service applications that are portable across environments, deployable continuously and scalable horizontally without architectural change. It sets out twelve practices: one codebase, explicit dependencies, config in the environment, backing services as attached resources, separate build, release and run stages, stateless processes, port binding, scaling through the process model, disposability, dev/prod parity, logs as event streams and admin tasks as one-off processes. Its real value is as a contract between an application and its platform: if a Spring Boot service follows it, Kubernetes can build, configure, scale, replace and observe it automatically, with no special handling.

Configuration that varies between environments, such as URLs, credentials, feature settings and resource sizes, should live in the environment, not in the code or the build artifact. Then the same image moves unchanged from test to production and only the injected configuration differs. On Kubernetes that means ConfigMaps exposed as environment variables or mounted application.yaml files, with secrets coming from a secret manager through External Secrets, never stored in Git or baked into images. In Spring Boot, bind it to @ConfigurationProperties records with @Validated, so a bad value fails at startup. Profiles are fine for structure but not for environment values; ShopNow ended three builds per release by moving URLs out of the jar.

It means three strictly separate stages. Build turns a commit into an immutable artifact, here a container image identified by its digest, built once by CI. Release combines that exact artifact with environment-specific configuration, for example the digest plus a production overlay committed to the GitOps repository, and every release is versioned and traceable. Run executes the release as processes, pods on Kubernetes, without changing code or config. Because nothing is modified at run time or rebuilt per environment, what was tested is what runs, any release can be traced to its commit, and rolling back simply means deploying a previous release. Patching code inside a running container breaks the model.

Because instances that hold no unique state can be added, removed or replaced at any time without losing data or breaking user sessions. Twelve-factor processes are stateless and share nothing; anything that must outlive a request goes to a backing service. HTTP sessions become stateless JWTs or Spring Session on Redis, uploaded files go to S3, carts and other data go to DynamoDB or a database, scheduled job locks use ShedLock or Kubernetes CronJobs, and in-flight work sits in queues with idempotent consumers. Local caches are fine only if losing them is harmless. ShopNow learned this when in-memory carts vanished as the autoscaler removed pods after a sale; moving carts to DynamoDB fixed it.

Run the same image everywhere and test against the same backing services as production, not lightweight substitutes. In Spring Boot tests, Testcontainers starts real dependencies in Docker, for example PostgreSQL 17 to match the production major version, Kafka and Redis, and the @ServiceConnection annotation wires their connection details into the application context automatically. For AWS services, LocalStack in Testcontainers emulates S3, SQS and DynamoDB closely enough for integration tests. Avoid H2 as a stand-in for PostgreSQL; ShopNow had a query that passed on H2 but failed in production because of case sensitivity. Keep the time, people and tools gaps small as well: deploy often, let developers deploy, and use identical manifests across environments.

Disposability means processes can be started or stopped at a moment's notice, which is what lets a platform scale, deploy and recover automatically. It has two halves. Fast startup keeps autoscaling and rollouts useful; for Java that means trimming classpath scanning and using the JDK AOT cache, or CRaC checkpoints, to reach readiness in seconds. Graceful shutdown means that on SIGTERM the service stops accepting new work, finishes in-flight requests within the termination grace period and releases its resources; Spring Boot supports this with server.shutdown=graceful. Because crashes still happen, work must also be safe to repeat: idempotent handlers, Kafka offsets committed after processing, and messages redelivered rather than lost.

As Kubernetes Jobs that use the same image and the same configuration as the application, so a migration or backfill runs exactly the code and settings that production runs. The note's example runs a Flyway migration as an Argo CD PreSync hook Job pinned to the image digest, with envFrom pulling in the service's ConfigMap and Secret, backoffLimit 0 and restartPolicy Never, so a failed migration stops the sync instead of retrying silently. Recurring tasks become CronJobs. Interactive investigation uses audited ephemeral debug containers rather than SSH into a server. The anti-pattern is running admin scripts from a laptop or a special admin host, with different code, credentials and dependencies.

The original factors were written for a single platform and a mostly HTTP world, so several concerns that matter today are missing. API first: contracts defined up front so teams can work in parallel. Telemetry: metrics and traces, not just logs, because distributed systems cannot be diagnosed without them. Security: authentication, authorisation, least-privilege identities and secret management, which the original text barely covers. Health: liveness and readiness probes, so orchestrators know when to route traffic to a process or restart it. Graceful degradation and resilience patterns for calls between services matter too. Kevin Hoffman's Beyond the Twelve-Factor App adds most of these, and modern platform checklists treat them as equally mandatory.

Assess the application against each factor, then fix violations incrementally in order of impact, not all at once. NovaBank's path is typical. Config and logs came first, moving per-environment properties files into ConfigMaps and Secrets Manager and replacing Log4j file appenders with JSON on stdout, because together they unblock containerisation. Then state and port binding: stateless JWTs instead of session replication, and a Spring Boot executable jar instead of a WebLogic WAR. Then disposability and parity, with faster startup, graceful shutdown and Testcontainers, while nightly batch moved to CronJobs or AWS Batch. Score each service on a compliance scorecard, deliver changes quarter by quarter, and keep the application running in production throughout.

Yes, though it should be applied pragmatically rather than as dogma. The factors became the default assumptions of container platforms: Kubernetes expects configuration injected at run time, stateless replicas it can reschedule, a fast and graceful lifecycle, logs on stdout and one-off Jobs, and serverless platforms such as Lambda assume the same. A service that ignores them fights its platform. Some guidance has aged: large or complex configuration is better mounted as files than spread across environment variables, and stateful workloads run well on managed services or operators. The methodology also needs the later additions of telemetry, security and health. Used as a checklist for the application-platform contract, it remains highly relevant.