Twelve-Factor App Nedir? Modern Uygulama Geliştirme Prensipleri

2011'de Heroku'nun kurucuları tarafından yayınlanan Twelve-Factor App metodolojisi, modern SaaS uygulamaları geliştirmek için 12 temel prensibi tanımlar. Cloud native çağında bu prensipler her zamankinden daha geçerlidir.

Neden 12-Factor?

Bu prensipler şu sorunları çözer:

• Geliştirme ve üretim ortamı arasındaki farklar
• Ölçekleme zorlukları
• Dağıtım karmaşıklığı
• Yeni ekip üyelerinin adaptasyon süresi

12 Prensip Detaylı Açıklama

I. Codebase — Tek Kod Tabanı

Her uygulama tek bir kod deposunda yaşar. Birden fazla deploy olabilir (staging, production), ama kod tabanı tektir.

Tek Repo → Staging Deploy
         → Production Deploy
         → Review Deploy

❌ Aynı kod tabanından farklı uygulamalar çıkarmayın.

II. Dependencies — Açık Bağımlılık Tanımı

Tüm bağımlılıklar açıkça tanımlanmalı. Sisteme bağımlılık olmamalı.

{
  "dependencies": {
    "next": "14.0.0",
    "react": "18.2.0",
    "gray-matter": "4.0.3"
  }
}

npm install veya pip install -r requirements.txt ile tüm bağımlılıklar kurulabilir olmalı.

III. Config — Ortam Değişkenleri

Konfigürasyon kodda değil, ortam değişkenlerinde tutulur:

# .env
DATABASE_URL=postgresql://user:pass@host:5432/db
API_KEY=sk-abcdef123456
ENVIRONMENT=production

// Kodda sabitleme yok
const dbUrl = process.env.DATABASE_URL;

IV. Backing Services — Takılabilir Servisler

Veritabanı, cache, e-posta servisi gibi dış bağımlılıklar, konfigürasyon değiştirerek takas edilebilir olmalı:

Geliştirme: DATABASE_URL=postgres://localhost/dev
Üretim:     DATABASE_URL=postgres://cloud-sql/prod

Kod değişikliği gerekmez.

V. Build, Release, Run — Aşama Ayrımı

Build (derleme), Release (sürüm) ve Run (çalışma) aşamaları kesin olarak ayrılmalıdır:

Build:   Kodu derle, bağımlılıkları çöz → Artifact
Release: Artifact + Config → Sürüm
Run:     Sürümü çalıştır → Çalışan uygulama

VI. Processes — Stateless Süreçler

Uygulama stateless süreçler olarak çalışmalı. Oturum bilgisi, dosya gibi durumsal veriler dış servislerde (Redis, veritabanı) tutulmalı.

❌ Yanlış: session verisini bellekte tut
✅ Doğru: session verisini Redis'te tut

VII. Port Binding — Port ile Servis Sunumu

Uygulama kendi web sunucusunu barındırmalı ve belirli bir port üzerinden servis sunmalı:

const server = app.listen(process.env.PORT || 3000, () => {
  console.log(`Server listening on port ${process.env.PORT}`);
});

VIII. Concurrency — Süreç ile Ölçekleme

Yatay ölçekleme, daha fazla süreç (process) ekleyerek yapılır:

Web:    2 instance
Worker: 4 instance
Cron:   1 instance

IX. Disposability — Hızlı Başlatma ve Düzgün Kapatma

Uygulamalar saniyeler içinde başlamalı ve graceful shutdown yapmalı:

process.on('SIGTERM', async () => {
  await server.close();
  await db.disconnect();
  process.exit(0);
});

X. Dev/Prod Parity — Ortam Benzerliği

Geliştirme, staging ve üretim ortamları mümkün olduğunca benzer olmalı:

• Aynı veritabanı (SQLite değil, PostgreSQL)
• Aynı bağımlılıklar
• Docker ile ortam standardizasyonu

XI. Logs — Olay Akışı

Loglar dosyaya yazılmaz, stdout'a gönderilir. Log toplama ve analizi dış araçlarla yapılır:

// ✅ Doğru
console.log(JSON.stringify({ level: 'info', message: 'Order created', orderId }));

// ❌ Yanlış
fs.appendFileSync('/var/log/app.log', message);

XII. Admin Processes — Tek Seferlik Görevler

Veritabanı migration, script çalıştırma gibi görevler tek seferlik süreçler olarak çalıştırılır:

npm run migrate
npm run seed
node scripts/cleanup.js

BilgeOne'da 12-Factor

BilgeOne platformu bu prensipleri nasıl uyguluyor:

| Prensip | Uygulama | |---------|----------| | Codebase | GitHub monorepo | | Dependencies | package.json | | Config | .env + Cloud Run env vars | | Backing Services | Supabase (PostgreSQL, Auth) | | Build/Release | GitHub Actions + Docker | | Processes | Stateless Next.js | | Port Binding | Cloud Run port injection | | Concurrency | Cloud Run auto-scaling | | Disposability | Container hızlı başlatma | | Parity | Docker ile ortam standardizasyonu | | Logs | Cloud Run stdout logging | | Admin | npm scripts |

Sonuç

Twelve-Factor App prensipleri, bulut çağının en temel yazılım geliştirme rehberidir. Bu prensiplere uygun geliştirilen uygulamalar daha ölçeklenebilir, bakımı kolay ve taşınabilir olur.

Cloud Native ve 12-Factor prensiplerini LabLudus platformunda DevOps kariyer yolunda pratik ederek öğrenin.