homelab-brain 🧠

homelab-library

3 dakika okuma süresi

homelab-library

Ailenin fiziksel + e-kitap koleksiyonunu tek self-hosted katalogda toplayan kişisel web uygulaması. CT 208’de çalışır, dışa library.ahmetkaraca.com (CT 206 NPM arkasında) ile açılır. Repo: ahmetem/homelab-library (private), yerel klon C:\Users\ahmet\Projeler\Proje\homelab-library.

Amaç ve özellikler

  • ISBN ile hızlı ekleme (metadata otomatik), arama/filtreleme, konum takibi (Kitaplık No › Raf No › Bölme No).
  • E-kitap saklama/indirme; tarayıcıda EPUB + PDF okuyucu ve okuma-konumu takibi.
  • Katalogda Küçük/Orta/Büyük görünüm, yazar filtresi, tür/yıl/okuma-durumu istatistik panosu, toplu CSV içe aktarma.
  • Kitaplar fiziksel (has_physical) veya e-kitap olabilir; konum yalnız fiziksel kitapta anlamlıdır. Konum silinince kitaplar kaybolmaz, ‘Konumsuz’a düşer.
  • Yazma yolu: rol/RLS bağlamlı + yazma rate-limit + audit kaydı.

Kalıcı kapsam dışı (bilinçli)

Ödünç takibi, sosyal özellikler (yorum/puan paylaşımı, çoklu-aile, halka açık profil) ve girişsiz/kamuya açık katalog yoktur — her yüzeyde giriş zorunludur.

Teknoloji yığını

  • Next.js 16 (App Router; Next 16’da middleware’in yeni adı src/proxy.ts), React 19, TypeScript, Node ≥22.
  • PostgreSQL 17.10 (paylaşımlı CT 200 cluster, 192.168.1.25); DB erişimi Kysely + pg, şema migration’ları node-pg-migrate (db/migrations), tipli erişim için kysely-codegen → src/types/db.generated.ts.
  • Kimlik: Auth.js / next-auth v5 credentials + argon2id; DB’de RLS (pgTAP testli) + audit_log.
  • Tailwind CSS, next-themes, zod, rate-limiter-flexible.
  • Tasarım sistemi DS-001: Turkuaz + Mercan renkleri, Nunito fontu (kullanıcı onaylı).

Veri modeli (konum hiyerarşisi)

4 kitaplık × 8 raf × 3 bölme = 96 konum; bu 96 konum production veritabanına yüklendi. (Ahmet’in fiziksel kitaplığının gerçek yapısı.)

Postgres erişim modeli (üç rol)

Paylaşımlı cluster’ı korumak için: app_owner (migration sahibi, limit 2), app_rls (uygulama, RLS uygulanır, limit 10), app_admin (yalnız bunda BYPASSRLS, limit 3). Production DB homelab_library.

Deploy ve CI/CD (CT 208)

  • Tek ortam (2026-06-26 kararı, bkz. 2026-06-26-homelab-library-tek-ortam-ci-kapili-deploy): ayrı staging yok; main’e push → CI → CI yeşilse workflow_run ile otomatik production deploy.
  • Deploy düzeni release-symlink: /opt/homelab-library/{releases/<ts>-<ref>/, current-production -> releases/..., shared/{.env, storage/}}; healthcheck geçmeden symlink atomik değiştirilmez, son 5 release tutulur, rollback.sh ile geri alınır. Uygulama 127.0.0.1:3000; CT-içi Caddy :80 ile NPM’e sunar (library.ahmetkaraca.com → 192.168.1.31:80 → Caddy → :3000).
  • Self-hosted GitHub Actions runner ct208-homelab CT 208 içinde (deploy kullanıcısı, systemd). Build, argon2 native modülü nedeniyle CT 208 içinde yapılır.
  • CI kapıları (authority): type-check, lint, unit + coverage (eşik %80), migrate-check (up→down→up), pgTAP RLS izolasyon, npm audit --audit-level=high, semgrep, gitleaks, changelog kapısı.
  • Geliştirme disiplini: ahmetem/web-agent-dev-standards submodule (core/ + profiles/nextjs-postgres-homelab + locales/tr); proje katmanı kuralı yalnız daraltabilir, gevşetemez.

Kalıcı kırılganlıklar / dikkat noktaları

  • Branch coverage %80.22 (142/177) — kıl payı geçer; src/lib’e kapsanmamış tek dal ekleyen değişiklik bile %79.66’ya düşürüp CI’ı (ve otomatik deploy’u) kırabilir.^[çıkarım]
  • CT 208 self-hosted runner build sırasında ara sıra anlık düşebiliyor (BlobNotFound); tekrarlarsa build anındaki bellek (4 GB) incelenecek.^[çıkarım]
  • CT 208 vzdump yedek işlerine eklendi (Tier-1 + Tier-2 PBS).

Türkçe ISBN/metadata stratejisi

Türkçe kitap metadata/ISBN için resmî ücretsiz API yok (Milli Kütüphane KAŞİF / ISBN ajansı yalnız web taraması). Çözüm: Google Books (country=TR) + kitapyurdu.com kazıyıcısı (öncelikli). Kitapyurdu detay sayfasından kırılgan CSS yerine JSON-LD @type:Book okunur (name/isbn/image/author/description/numberOfPages); tür kategori yolundan, yıl ‘Yayın Tarihi’ satırından. Kitapyurdu arama ISBN’i indekslemediğinden ISBN→başlık (Open Library/Google) çözülüp sadeleştirilmiş başlıkla aranır, yalnız aynı-ISBN’li sonuç kabul edilir.

CT 208 ortamı

Debian 12 / systemd 252 unprivileged LXC; 2 vCPU / 4 GB RAM / 1 GB swap / 16 GB rootfs.

İlgili

Grafik Görünümü

Backlinkler