A practical review of the twelve factors for backends running on AWS, GCP and Kubernetes today, which ones every service should still follow, where secrets managers, containers and agents have changed the advice, and how to apply them without a pile of infrastructure scripts.

The twelve-factor app was written in 2011 for apps on a single PaaS, and much of it now describes how containers on ECS, Cloud Run or Kubernetes already behave. That makes it easy to nod along and still break it.
The usual breaks are config and secrets, the gap between laptop and production, and one-off scripts outside the deploy pipeline. This guide goes through all twelve factors, what still holds, and a service that follows them by default.
The methodology lists twelve practices for software-as-a-service backends, and since it was open-sourced in 2024 it has been revised in the open. Here is each one, with how it applies today:
Factors II, V, VII and VIII come almost for free with containers and a managed runtime. The ones that still cause incidents are the factors where the platform cannot enforce the rule for you.
Config (III). The original advice was to put all config, credentials included, in environment variables, which the config factor defines as anything that varies between deploys. Plain env vars are now considered a weak place for secrets, because they leak into crash dumps, child processes and env output in CI logs. Keep non-secret settings in env, put credentials in AWS Secrets Manager or Google Secret Manager, and inject them at runtime with access limited to the service that needs them.
Backing services (IV). The factor says a local Postgres and a managed one should be interchangeable through config. In practice, the attachment itself is where effort goes: each environment needs the database created, a user, network access and a connection string stored somewhere, and that is usually a Terraform module per resource type.
Dev/prod parity (X). The dev/prod parity factor names three gaps, time, personnel and tools, and the tools gap is the one that persists. A laptop running SQLite and an in-process queue behaves differently from RDS and SQS, so bugs in transactions, ordering and retries only appear after deploy.
Admin processes (XII). Migrations run by hand from a laptop, or cron jobs configured in a console with a different version of the code, break the rule that admin tasks ship with the release they belong to.
Kubernetes, ECS and Cloud Run all stop containers with SIGTERM followed by SIGKILL after a grace period, so disposability now has a concrete meaning: stop accepting new work on SIGTERM, finish in-flight requests, and make background jobs idempotent so a job killed halfway can run again. Concurrency means separate process types, such as an API and a queue consumer, that scale independently, which on these platforms is separate services or deployments rather than one container running both.
The factors were written for human teams, but they matter more when coding agents write a large share of the code. An agent working in a repo where config, infrastructure and admin scripts all live outside the code has to guess at them, while an agent working in a repo where backing services and schedules are declared in the code can see and change them in one diff. The config rule also gains a new reason: secrets that never enter the repo or a .env file cannot be read or leaked by the agent.
Encore is a backend framework with built-in infrastructure, and several factors fall out of its design: backing services are declared in the code and attached per environment, secrets are injected at runtime from your cloud's secret manager, migrations and scheduled jobs ship with the release, and encore run starts the same kind of Postgres and Pub/Sub you use in production. The example is a small Go service that touches factors III, IV, X, XI and XII.
Run in your terminal to get started locally.
The migration is the admin process for the schema, applied by Encore on every deploy and on encore run:
-- invoices/migrations/1_invoices.up.sql
CREATE TABLE invoices (
id BIGSERIAL PRIMARY KEY,
customer_id TEXT NOT NULL,
amount_cents BIGINT NOT NULL,
due_at TIMESTAMPTZ NOT NULL,
reminded_at TIMESTAMPTZ
);
CREATE INDEX invoices_due ON invoices (due_at) WHERE reminded_at IS NULL;
The service declares its database, a secret for the email provider and a cron job for reminders:
// invoices/invoices.go
package invoices
import (
"context"
"encore.dev/cron"
"encore.dev/rlog"
"encore.dev/storage/sqldb"
)
// Backing service: attached per environment, never a connection string in code.
var db = sqldb.NewDatabase("invoices", sqldb.DatabaseConfig{
Migrations: "./migrations",
})
// Config: the value is injected at runtime and never stored in the repo.
var secrets struct {
EmailAPIKey string
}
// Admin process: the schedule ships with the release that contains the code.
var _ = cron.NewJob("invoice-reminders", cron.JobConfig{
Title: "Send reminders for overdue invoices",
Schedule: "0 8 * * *",
Endpoint: SendReminders,
})
type ReminderResult struct {
Sent int `json:"sent"`
}
//encore:api private
func SendReminders(ctx context.Context) (*ReminderResult, error) {
rows, err := db.Query(ctx, `
UPDATE invoices SET reminded_at = now()
WHERE id IN (
SELECT id FROM invoices
WHERE due_at < now() AND reminded_at IS NULL
ORDER BY due_at LIMIT 100
FOR UPDATE SKIP LOCKED
)
RETURNING id, customer_id`)
if err != nil {
return nil, err
}
defer rows.Close()
sent := 0
for rows.Next() {
var id int64
var customerID string
if err := rows.Scan(&id, &customerID); err != nil {
return nil, err
}
if err := sendReminder(ctx, customerID, id); err != nil {
rlog.Error("reminder failed", "invoice_id", id, "err", err)
continue
}
sent++
}
// Logs: structured fields on stdout, collected by the platform.
rlog.Info("reminders sent", "count", sent)
return &ReminderResult{Sent: sent}, rows.Err()
}
func sendReminder(ctx context.Context, customerID string, invoiceID int64) error {
_ = secrets.EmailAPIKey // Call the email provider with this key.
return nil
}
encore run starts Postgres, applies the migration and serves the endpoint, so dev/prod parity covers the database itself rather than a stand-in. Cron jobs do not run locally, so call SendReminders from the local dashboard or a test while developing; in deployed environments the schedule is Encore platform managed, with no extra infrastructure in your account. On deploy to your AWS or GCP account, the database becomes RDS or Cloud SQL and the secret is read from your cloud's secret manager at runtime. The reminder query claims rows with SKIP LOCKED and marks them in the same statement, so a retried or overlapping run does not remind the same invoice twice.
An agent asked to add late fees writes a second migration, the query and, if needed, a new job in one change, and runs the service locally against that Postgres, without a separate infrastructure repo to update.
Best fit: teams starting a new backend who want it to follow the twelve factors from the first commit, running in their own AWS or GCP account.
SIGTERM with a graceful drain.A twelve-factor app follows a methodology for building software-as-a-service backends that are portable, scale out by adding processes and deploy continuously. The twelve factors cover one codebase per app, declared dependencies, config outside the code, backing services as attached resources, separate build and run stages, stateless processes, port binding, concurrency, disposability, dev/prod parity, logs as event streams and one-off admin processes.
Yes. Most factors describe how containers on Kubernetes, ECS or Cloud Run already expect apps to behave, such as stateless processes, fast startup, graceful shutdown and logs on stdout. The factor on config is the one usually applied differently today, keeping secrets in a secrets manager rather than in plain environment variables.
Dev/prod parity means keeping development and production as similar as possible: the same backing services such as Postgres rather than SQLite, deploys within hours of writing code, and the same people writing and deploying it. Tools that run the same database and queue locally make the backing service gap the easiest one to close.
It was written in 2011 by Adam Wiggins and other engineers at Heroku, based on what they saw across many apps on the platform. In November 2024 the methodology was open-sourced so the community could update it for modern cloud platforms.
Deploy to your cloud on AWS and Google Cloud
without managing infrastructure
Encore lets developers and agents define application infrastructure directly in code, then automatically provisions it from local development to production in your AWS or GCP account.