From 4a6234f3952f884627d60f7bd975a09119930c69 Mon Sep 17 00:00:00 2001 From: Poyraz Avsever Date: Sun, 14 Jun 2026 11:15:47 +0300 Subject: [PATCH] Remove outdated installation and operational documentation for Neta, including full-stack, app-only, Coolify, and Dokploy setups, as well as environment variables and troubleshooting sections. This cleanup streamlines the content for better clarity and focus on current practices. --- content/01-dokumantasyon.md | 72 --------- content/02-ozellikler.md | 112 ------------- content/03-mimari.md | 113 -------------- content/04-kurulum-modlari.md | 97 ------------ content/05-full-stack-kurulum.md | 184 ---------------------- content/06-coolify-kurulum.md | 136 ---------------- content/07-dokploy-kurulum.md | 128 --------------- content/08-app-only-kurulum.md | 103 ------------ content/09-ilk-admin-ve-kayit-kilidi.md | 127 --------------- content/10-operasyon.md | 153 ------------------ content/11-env-degiskenleri.md | 192 ----------------------- content/12-sorun-giderme.md | 199 ------------------------ content/13-guvenlik-ve-sinirlar.md | 129 --------------- 13 files changed, 1745 deletions(-) delete mode 100644 content/01-dokumantasyon.md delete mode 100644 content/02-ozellikler.md delete mode 100644 content/03-mimari.md delete mode 100644 content/04-kurulum-modlari.md delete mode 100644 content/05-full-stack-kurulum.md delete mode 100644 content/06-coolify-kurulum.md delete mode 100644 content/07-dokploy-kurulum.md delete mode 100644 content/08-app-only-kurulum.md delete mode 100644 content/09-ilk-admin-ve-kayit-kilidi.md delete mode 100644 content/10-operasyon.md delete mode 100644 content/11-env-degiskenleri.md delete mode 100644 content/12-sorun-giderme.md delete mode 100644 content/13-guvenlik-ve-sinirlar.md diff --git a/content/01-dokumantasyon.md b/content/01-dokumantasyon.md deleted file mode 100644 index 32ba478..0000000 --- a/content/01-dokumantasyon.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Dokümantasyon -description: Neta kurulum ve kullanım dokümantasyonu. -order: 1 ---- - -# Neta Dokümantasyonu - -Neta, freelancerlar için tasarlanmış self-host edilebilir bir çalışma alanıdır. Amaç; müşteri, proje, görev, finans, takvim, günlük ve performans takibini tek bir panelde toplamak ve freelancerların günlük operasyonlarını harici SaaS araçlarına bağımlı kalmadan yönetebilmesini sağlamaktır. - -Bu dokümantasyon, Neta'yı tanımak, kendi sunucunda çalıştırmak ve ilk kurulumu doğru tamamlamak için hazırlanmıştır. İçerikler hem teknik kullanıcılar hem de Coolify, Dokploy gibi panel tabanlı araçlarla kurulum yapmak isteyenler için adım adım düzenlenmiştir. - -## Kimler İçin? - -Neta özellikle şu kullanıcılar için uygundur: - -- Tek başına çalışan freelancerlar -- Küçük ölçekli danışmanlar -- Yazılım, tasarım, içerik, pazarlama veya danışmanlık hizmeti veren bağımsız profesyoneller -- Müşteri ve proje operasyonlarını tek panelde yönetmek isteyen self-host kullanıcıları -- Kendi verisini kendi sunucusunda tutmak isteyen teknik kullanıcılar - -Neta'nın ilk MVP sürümü tek admin odaklıdır. Yani sistem ilk kurulumda bir admin hesabı oluşturur ve sonrasında public kayıt ekranını kapatır. Bu yaklaşım, kişisel kullanım ve tek freelancer senaryosu için daha kontrollü bir güvenlik modeli sağlar. - -## Self-Host Yaklaşımı - -Neta iki farklı kurulum modeli destekler: - -- **Full-stack kurulum:** Neta uygulaması, PostgreSQL, Supabase Auth, PostgREST, Storage ve proxy servisleri aynı Docker Compose yapısı içinde çalışır. -- **App-only kurulum:** Neta uygulaması mevcut bir Supabase veya Supabase uyumlu backend'e bağlanır. - -İlk MVP için önerilen kurulum **full-stack self-host** modudur. Bu modda harici Supabase hesabına ihtiyaç yoktur. Veritabanı, kimlik doğrulama ve dosya depolama servisleri kendi sunucunda çalışır. - -## Dokümantasyonda Neler Var? - -Bu dokümantasyon şu bölümlerden oluşur: - -- Özellikler -- Teknik mimari -- Kurulum modları -- Full-stack kurulum -- Coolify kurulumu -- Dokploy kurulumu -- App-only kurulum -- İlk admin hesabı ve kayıt kilidi -- Operasyon, sağlık kontrolü, yedekleme ve geri yükleme -- Ortam değişkenleri -- Sorun giderme -- Güvenlik ve mevcut sınırlar - -## Önemli Kavramlar - -Neta'yı doğru kurmak için şu ayrımları bilmek önemlidir: - -- `.env` dosyası Docker Compose kurulumlarında kullanılır. -- `.env.local` dosyası lokal Next.js geliştirme sırasında kullanılır. -- Full-stack modda migration dosyaları `neta-migrations` servisi tarafından otomatik çalıştırılır. -- App-only modda migration dosyalarını bağlandığın Supabase projesinin veritabanında manuel çalıştırman gerekir. -- İlk admin oluşturulduktan sonra `/register` sayfası kapanır ve giriş için `/login` kullanılır. - -## Önerilen Başlangıç - -Kendi sunucusunda hızlı kurulum yapmak isteyen kullanıcılar için önerilen yol: - -```bash -node scripts/generate-full-stack-env.mjs > .env -docker compose -f docker-compose.full.yml up -d --build -sh ./scripts/selfhost-doctor.sh -``` - -Ardından tarayıcıdan Neta adresini açıp ilk admin hesabını oluşturabilirsin. - diff --git a/content/02-ozellikler.md b/content/02-ozellikler.md deleted file mode 100644 index a638b78..0000000 --- a/content/02-ozellikler.md +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Özellikler -description: Neta'nın freelancerlar için sunduğu temel özellikler. -order: 2 ---- - -# Özellikler - -Neta, freelancerların günlük iş akışını tek bir yerde yönetebilmesi için tasarlanmıştır. MVP kapsamındaki özellikler, operasyonel kullanım odağındadır: müşteri ilişkileri, proje takibi, görev yönetimi, finansal görünürlük ve kişisel performans takibi. - -## Dashboard - -Dashboard, çalışma alanının ana ekranıdır. Aktif işlerin, görevlerin, gelir durumunun ve genel performans göstergelerinin hızlıca görülmesini sağlar. - -Dashboard üzerinde amaç, kullanıcının gün içinde neye odaklanması gerektiğini hızlıca anlamasıdır. Bu nedenle Neta, verileri dekoratif bir özet yerine aksiyon alınabilir bir operasyon paneli şeklinde sunar. - -## Müşteri Yönetimi - -Müşteri modülü, freelancerın müşteri portföyünü takip etmesini sağlar. - -Bu bölümde: - -- Müşteri kayıtları tutulabilir. -- Müşteri durumu izlenebilir. -- Müşteriler projelerle ilişkilendirilebilir. -- Temel iletişim ve iş takibi bilgileri tek yerde saklanabilir. - -Bu yapı, müşteri bilgilerini dağınık notlar, e-postalar veya ayrı tablolar yerine merkezi bir sistemde tutmayı hedefler. - -## Proje Yönetimi - -Proje modülü, müşteri işleri ve iç operasyonlar için kullanılabilir. - -Projeler üzerinden: - -- Proje adı ve açıklaması tutulabilir. -- Müşteri ilişkisi kurulabilir. -- Durum ve öncelik takip edilebilir. -- İlerleme ve teslim süreçleri izlenebilir. - -Neta'nın proje yapısı, freelancerların aynı anda birden fazla müşteri ve teslimat üzerinde çalıştığı gerçek iş akışına göre tasarlanmıştır. - -## Görev Takibi - -Görev yönetimi, günlük operasyonun merkezindedir. - -Görevler: - -- Projelerle ilişkilendirilebilir. -- Öncelik ve durum bilgisi taşıyabilir. -- Teslim tarihi ile planlanabilir. -- Günlük çalışma akışında takip edilebilir. - -Amaç, freelancerın hem müşteri işlerini hem de kendi operasyonel görevlerini tek sistemde yönetebilmesidir. - -## Finans Takibi - -Finans modülü, gelir ve giderleri takip etmek için kullanılır. - -Bu bölümde: - -- Gelir kayıtları tutulabilir. -- Gider kayıtları tutulabilir. -- Nakit akışı izlenebilir. -- Finansal durum tablo ve grafiklerle analiz edilebilir. - -MVP aşamasında bu modül, tam muhasebe sistemi yerine freelancerın kendi finansal görünürlüğünü artırmayı hedefler. - -## Takvim - -Takvim, işlerin tarih bazlı görünümünü sağlar. Görevler, teslim tarihleri ve planlanan işler takvim üzerinden takip edilebilir. - -Takvim modülü, özellikle birden fazla müşteri ve proje ile çalışan kullanıcıların zaman planlamasını kolaylaştırır. - -## Günlük ve Performans Takibi - -Journal modülü, kullanıcının ruh hali, enerji seviyesi, çalışma memnuniyeti ve günlük notlarını kaydetmesine yardımcı olur. - -Bu veriler zaman içinde kişisel performans analizi için kullanılabilir. Amaç, sadece iş çıktısını değil, çalışma sürdürülebilirliğini de takip etmektir. - -## AI Asistan - -Neta içinde AI destekli bir asistan bulunur. Bu asistan, bağlanan sağlayıcıya göre görevler, finans verileri ve iş akışı hakkında yardımcı olabilir. - -Desteklenebilecek sağlayıcılar: - -- OpenAI -- Google Gemini -- Groq -- Yerel veya özel modeller - -AI ayarları uygulama içinden veya environment değişkenleri ile yapılandırılabilir. - -## Client Portal - -Client portal, müşterilerin kendi projelerine ait belirli bilgileri görebilmesi için tasarlanmıştır. - -MVP kapsamında portal kontrollü ve sınırlı erişim modeline göre ele alınır. Amaç, müşteriye şeffaflık sağlarken freelancerın iç operasyon verilerini korumaktır. - -## MVP Dışında Kalanlar - -İlk self-host MVP sürümünde şu özellikler bilinçli olarak sınırlıdır: - -- Çoklu ekip üyeliği -- Karmaşık rol yönetimi -- Çok tenantlı SaaS modeli -- Otomatik faturalandırma entegrasyonları -- Gelişmiş muhasebe sistemi -- Yüksek erişilebilirlik mimarisi - -Bu sınırlar, Neta'nın ilk aşamada basit, kurulabilir ve güvenli bir kişisel freelancer işletim sistemi olmasını sağlar. - diff --git a/content/03-mimari.md b/content/03-mimari.md deleted file mode 100644 index 4f1bba8..0000000 --- a/content/03-mimari.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Mimari -description: Neta'nın teknik mimarisi ve servis yapısı. -order: 3 ---- - -# Mimari - -Neta, modern web teknolojileri ve Supabase uyumlu açık kaynak servisler üzerine kuruludur. Full-stack self-host modunda uygulama ve backend servisleri tek bir Docker Compose yapısı içinde çalışır. - -## Genel Yapı - -Full-stack kurulumda çalışan ana servisler: - -- `neta-web`: Next.js uygulaması -- `neta-db`: PostgreSQL ve pgvector -- `neta-auth`: Supabase Auth -- `neta-rest`: PostgREST -- `neta-storage`: Supabase Storage -- `neta-supabase-proxy`: Nginx tabanlı API proxy -- `neta-migrations`: Veritabanı migration runner - -Bu servisler birlikte Neta'nın harici Supabase hesabına ihtiyaç duymadan çalışmasını sağlar. - -## Next.js Uygulaması - -Neta'nın kullanıcı arayüzü Next.js App Router üzerinde çalışır. Uygulama production ortamında standalone build olarak container içine alınır. - -Uygulama: - -- Dashboard ve modül sayfalarını sunar. -- Supabase Auth ile oturum yönetimi yapar. -- PostgREST üzerinden veritabanı işlemlerini gerçekleştirir. -- Server action ve API route yapıları ile bazı işlemleri sunucu tarafında yürütür. - -## PostgreSQL ve pgvector - -Veritabanı olarak PostgreSQL kullanılır. Full-stack modda `pgvector/pgvector:pg16` imajı tercih edilir. - -PostgreSQL şu verileri saklar: - -- Kullanıcı profilleri -- Müşteriler -- Projeler -- Görevler -- Finans kayıtları -- Journal kayıtları -- Client portal ilişkileri -- Uygulama ayarları - -pgvector desteği, ileride AI ve embedding tabanlı özellikler için hazır altyapı sağlar. - -## Supabase Auth - -Kimlik doğrulama için Supabase Auth kullanılır. Full-stack modda Auth servisi Neta'nın kendi PostgreSQL veritabanına bağlanır. - -Auth servisi: - -- Kullanıcı kaydı -- Parola ile giriş -- JWT üretimi -- Oturum yönetimi -- Auth tablolarının migration işlemleri - -gibi işleri yürütür. - -Neta, ilk admin hesabı oluşturulduktan sonra public kayıt akışını kapatır. Bu kontrol veritabanı fonksiyonu ve trigger ile desteklenir. - -## PostgREST - -PostgREST, PostgreSQL üzerindeki public schema için REST API sağlar. Supabase istemcisi uygulama içinde bu API üzerinden veri okuma ve yazma işlemleri yapar. - -Row Level Security politikaları PostgreSQL tarafında uygulanır. Böylece veri erişimi uygulama koduna ek olarak veritabanı seviyesinde de kontrol edilir. - -## Supabase Storage - -Dosya depolama için Supabase Storage API kullanılır. Full-stack modda dosyalar Docker volume içinde lokal disk backend ile saklanır. - -Bu yapı MVP için yeterlidir. Daha ileri production senaryolarında S3 uyumlu harici storage desteği değerlendirilebilir. - -## Nginx Proxy - -`neta-supabase-proxy`, Supabase uyumlu API giriş noktası sağlar. - -Proxy üzerinden: - -- `/auth/v1` -- `/rest/v1` -- `/storage/v1` -- `/health` - -gibi endpointler ilgili servislere yönlendirilir. - -Uygulama container içinden internal URL ile bu proxy'ye bağlanır. Kullanıcı tarafında ise public Supabase API URL değeri kullanılır. - -## Migration Runner - -`neta-migrations` servisi tek seferlik çalışan bir container'dır. Görevi, Supabase Auth ve Storage tabloları hazır olduktan sonra Neta'nın kendi SQL dosyalarını doğru sırayla uygulamaktır. - -Full-stack modda kullanıcı migration dosyalarını manuel çalıştırmaz. Compose başlatıldığında migration runner bu işi otomatik yapar. - -## Veri Akışı - -Tipik bir istek akışı şöyledir: - -1. Kullanıcı tarayıcıdan Neta arayüzünü açar. -2. Next.js uygulaması oturum bilgisini Supabase Auth ile doğrular. -3. Veri istekleri PostgREST üzerinden PostgreSQL'e gider. -4. PostgreSQL RLS politikaları erişim kontrolünü uygular. -5. Dosya işlemleri Storage API üzerinden volume tabanlı depoya yazılır. - -Bu mimari, self-host kullanım için sade, taşınabilir ve Docker tabanlı bir yapı sağlar. - diff --git a/content/04-kurulum-modlari.md b/content/04-kurulum-modlari.md deleted file mode 100644 index b75192f..0000000 --- a/content/04-kurulum-modlari.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: Kurulum Modları -description: Full-stack ve app-only kurulum seçenekleri. -order: 4 ---- - -# Kurulum Modları - -Neta iki farklı kurulum modeli destekler. Doğru modeli seçmek, migration, environment ve veri konumu açısından önemlidir. - -## Full-Stack Kurulum - -Full-stack kurulumda Neta ile birlikte gerekli backend servisleri de aynı sunucuda çalışır. - -Bu mod şunları içerir: - -- Neta web uygulaması -- PostgreSQL -- Supabase Auth -- PostgREST -- Supabase Storage -- Nginx proxy -- Otomatik migration runner - -Bu modda harici Supabase hesabına gerek yoktur. İlk MVP için önerilen self-host yolu budur. - -## App-Only Kurulum - -App-only kurulumda sadece Neta uygulaması çalışır. Veritabanı, Auth, Storage ve API servisleri mevcut bir Supabase projesinden veya Supabase uyumlu bir backend'den sağlanır. - -Bu mod şu durumlarda uygundur: - -- Zaten aktif bir Supabase projen varsa -- Veritabanını managed servis olarak kullanmak istiyorsan -- Sadece Neta arayüzünü kendi sunucunda yayınlamak istiyorsan - -Bu modda migration dosyalarını bağlandığın Supabase projesinin veritabanında manuel çalıştırman gerekir. - -## Hangi Mod Seçilmeli? - -Çoğu self-host kullanıcısı için önerilen seçenek: - -```text -Full-stack kurulum -``` - -Çünkü bu mod: - -- Harici servis gerektirmez. -- Migration işlemlerini otomatik yapar. -- Coolify ve Dokploy gibi araçlarda tek Compose dosyasıyla çalışır. -- Veriyi aynı sunucuda tutar. - -App-only mod ise daha ileri kullanıcılar veya mevcut Supabase altyapısını kullanmak isteyenler için uygundur. - -## `.env` ve `.env.local` Ayrımı - -Bu ayrım kurulum hatalarının en sık sebebidir. - -Docker Compose kurulumlarında `.env` dosyası kullanılır. - -```bash -node scripts/generate-full-stack-env.mjs > .env -docker compose -f docker-compose.full.yml up -d --build -``` - -Lokal Next.js geliştirme sırasında ise Next.js `.env.local` dosyasını okur. - -```bash -pnpm dev -``` - -Eğer `.env.local` hosted Supabase projesine bakıyorsa, lokal geliştirme ortamında self-host Docker veritabanına değil hosted Supabase'e bağlanırsın. - -## Migration Nerede Çalışır? - -Full-stack modda: - -- Migration işlemleri `neta-migrations` servisi tarafından otomatik yapılır. -- Kullanıcının SQL dosyalarını manuel çalıştırması gerekmez. - -App-only modda: - -- Migration dosyaları mevcut Supabase projesinde çalıştırılmalıdır. -- Uygulamanın bağlandığı `NEXT_PUBLIC_SUPABASE_URL` hangi projeyi gösteriyorsa, migration da o projenin veritabanında olmalıdır. - -## Coolify ve Dokploy İçin Öneri - -Coolify ve Dokploy gibi araçlarda en pratik yöntem: - -- Compose dosyası olarak `docker-compose.full.yml` seçmek -- Generated environment değerlerini panelde tanımlamak -- Neta domainini `neta-web:3000` servisine yönlendirmek -- Supabase API gerekiyorsa `neta-supabase-proxy:8000` servisini ayrıca yayınlamak - -Bu yapı, kullanıcıya harici Supabase hesabı gerektirmeden tam self-host deneyimi sağlar. - diff --git a/content/05-full-stack-kurulum.md b/content/05-full-stack-kurulum.md deleted file mode 100644 index 8a0158e..0000000 --- a/content/05-full-stack-kurulum.md +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: Full-Stack Kurulum -description: Neta'yı harici servis gerektirmeden self-host etme rehberi. -order: 5 ---- - -# Full-Stack Kurulum - -Full-stack kurulum, Neta'yı harici Supabase hesabına ihtiyaç duymadan kendi sunucunda çalıştırmanın önerilen yoludur. Bu modda uygulama, veritabanı, kimlik doğrulama, REST API, storage ve proxy servisleri birlikte çalışır. - -## Gereksinimler - -Sunucuda şu bileşenler bulunmalıdır: - -- Docker -- Docker Compose -- Git -- En az 2 GB RAM -- Kalıcı disk alanı -- Yayın yapılacak bir domain veya test için localhost - -Production kullanımı için domain ve HTTPS önerilir. - -## Repository'yi Al - -```bash -git clone https://github.com/poyrazavsever/neta.git -cd neta -``` - -## Environment Dosyasını Üret - -Full-stack kurulum için gerekli secret ve token değerlerini üret: - -```bash -node scripts/generate-full-stack-env.mjs > .env -``` - -Bu komut şu değerleri üretir: - -- `NEXT_PUBLIC_SITE_URL` -- `NETA_PORT` -- `NEXT_PUBLIC_SUPABASE_URL` -- `SUPABASE_API_PORT` -- `NEXT_PUBLIC_SUPABASE_ANON_KEY` -- `SUPABASE_SERVICE_ROLE_KEY` -- `JWT_SECRET` -- `POSTGRES_PASSWORD` -- `POSTGRES_PORT` -- `JWT_EXPIRY` -- `SMTP_ADMIN_EMAIL` - -Domain ile yayın yapacaksan `.env` içindeki URL değerlerini deploy öncesi düzenle. - -Örnek: - -```env -NEXT_PUBLIC_SITE_URL=https://app.example.com -NEXT_PUBLIC_SUPABASE_URL=https://supabase.example.com -``` - -Local test için varsayılan değerler yeterlidir. - -## Stack'i Başlat - -```bash -docker compose -f docker-compose.full.yml up -d --build -``` - -Bu komut şu işlemleri yapar: - -1. Neta uygulamasını build eder. -2. PostgreSQL servisini başlatır. -3. Supabase Auth migrationlarını çalıştırır. -4. Storage ve PostgREST servislerini başlatır. -5. Neta migration dosyalarını uygular. -6. Web uygulamasını başlatır. - -## Sağlık Kontrolü - -Kurulumdan sonra health check çalıştır: - -```bash -sh ./scripts/selfhost-doctor.sh -``` - -Bu script şunları kontrol eder: - -- Docker daemon erişimi -- Container çalışma durumları -- Migration runner başarı durumu -- Veritabanı health durumu -- Web health endpointi -- Supabase proxy endpointi -- Auth settings endpointi -- Neta tablolarının varlığı - -İstersen gerçek Auth akışını da test edebilirsin: - -```bash -NETA_DOCTOR_AUTH_SMOKE=1 sh ./scripts/selfhost-doctor.sh -``` - -Bu kontrol temiz kurulumda test kullanıcısı oluşturabilir. İlk admin akışını manuel test etmek istiyorsan bu opsiyonu çalıştırmadan önce dikkatli ol. - -## İlk Admin Hesabı - -Stack hazır olduktan sonra: - -```text -https://senin-domainin/register -``` - -veya local testte: - -```text -http://localhost:3000/register -``` - -sayfasını aç. - -İlk kayıt olan kullanıcı admin kabul edilir. İlk profil oluştuktan sonra public kayıt kapanır ve `/register` sayfası artık `/login` sayfasına yönlendirir. - -## Kullanılan Portlar - -Varsayılan portlar: - -- Neta web: `3000` -- Supabase API proxy: `8000` -- PostgreSQL: `54322` - -Bu portlar `.env` dosyasından değiştirilebilir: - -```env -NETA_PORT=3000 -SUPABASE_API_PORT=8000 -POSTGRES_PORT=54322 -``` - -## Container Listesi - -Çalışan servisleri görmek için: - -```bash -docker ps -``` - -Beklenen containerlar: - -- `neta-web` -- `neta-db` -- `neta-auth` -- `neta-rest` -- `neta-storage` -- `neta-supabase-proxy` - -`neta-migrations` tek seferlik çalışır ve başarıyla çıkmış olmalıdır. - -## Durdurma ve Yeniden Başlatma - -Durdurmak için: - -```bash -docker compose -f docker-compose.full.yml stop -``` - -Yeniden başlatmak için: - -```bash -docker compose -f docker-compose.full.yml up -d -``` - -Volume silinmediği sürece veriler korunur. - -## Verileri Sıfırlama - -Test ortamında tüm verileri silmek istersen: - -```bash -docker compose -f docker-compose.full.yml down -v -``` - -Bu komut veritabanı ve storage volume'larını siler. Production ortamında yedek almadan kullanılmamalıdır. - diff --git a/content/06-coolify-kurulum.md b/content/06-coolify-kurulum.md deleted file mode 100644 index a27d4c1..0000000 --- a/content/06-coolify-kurulum.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Coolify Kurulumu -description: Neta'yı Coolify üzerinde full-stack olarak yayınlama. -order: 6 ---- - -# Coolify Kurulumu - -Coolify, Neta'yı self-host etmek için uygun bir platformdur. Önerilen yöntem, `docker-compose.full.yml` dosyasını kullanarak full-stack kurulum yapmaktır. - -## Kurulum Modeli - -Coolify üzerinde önerilen model: - -```text -Full-stack Neta kurulumu -``` - -Bu modelde Neta ile birlikte PostgreSQL, Auth, PostgREST, Storage ve proxy servisleri de aynı Compose uygulamasında çalışır. - -## Repository Bağlama - -Coolify içinde yeni bir proje oluştur ve Neta repository'sini bağla. - -Compose dosyası olarak: - -```text -docker-compose.full.yml -``` - -seçilmelidir. - -## Environment Değerlerini Üret - -Lokal ortamda veya sunucuda şu komutu çalıştır: - -```bash -node scripts/generate-full-stack-env.mjs -``` - -Komutun ürettiği değerleri Coolify environment paneline ekle. - -En önemli değerler: - -- `NEXT_PUBLIC_SITE_URL` -- `NEXT_PUBLIC_SUPABASE_URL` -- `NEXT_PUBLIC_SUPABASE_ANON_KEY` -- `SUPABASE_SERVICE_ROLE_KEY` -- `JWT_SECRET` -- `POSTGRES_PASSWORD` -- `NETA_PORT` -- `SUPABASE_API_PORT` -- `POSTGRES_PORT` - -## Domain Ayarları - -Neta uygulaması için domain: - -```text -neta-web:3000 -``` - -servisine yönlendirilmelidir. - -Supabase API için ayrı domain kullanacaksan: - -```text -neta-supabase-proxy:8000 -``` - -servisine yönlendirilmelidir. - -Örnek yapı: - -```text -https://app.example.com -> neta-web:3000 -https://api.example.com -> neta-supabase-proxy:8000 -``` - -Bu durumda environment değerleri şöyle olmalıdır: - -```env -NEXT_PUBLIC_SITE_URL=https://app.example.com -NEXT_PUBLIC_SUPABASE_URL=https://api.example.com -``` - -## Tek Domain Kullanımı - -Coolify üzerinde en temiz yapı ayrı API domain kullanmaktır. Tek domain altında path-based routing yapılacaksa proxy kuralları dikkatli ayarlanmalıdır. - -MVP için önerilen pratik yaklaşım: - -- Bir domain Neta uygulaması için -- Bir subdomain Supabase API için - -## Deploy - -Environment değerleri eklendikten sonra deploy başlatılır. - -Deploy sırasında: - -- Web uygulaması build edilir. -- Veritabanı başlatılır. -- Supabase Auth kendi migrationlarını uygular. -- Neta migrationları `neta-migrations` servisi ile çalışır. -- Web uygulaması proxy ve migration tamamlanmadan başlamaz. - -## İlk Kontrol Listesi - -Deploy sonrası şunları kontrol et: - -- `neta-db` healthy durumda mı? -- `neta-supabase-proxy` healthy durumda mı? -- `neta-web` healthy durumda mı? -- `neta-migrations` başarıyla tamamlandı mı? -- `/register` sayfası ilk admin için açılıyor mu? -- İlk admin oluşturulduktan sonra `/register` kapanıyor mu? - -## Sık Yapılan Hatalar - -### Yanlış Compose Dosyası - -Full-stack self-host için `docker-compose.full.yml` kullanılmalıdır. Sadece `docker-compose.yml` kullanılırsa uygulama harici Supabase bekler. - -### Eksik Environment - -Coolify panelinde zorunlu env değerleri eksikse Compose build veya runtime sırasında hata verir. - -### Yanlış Public URL - -`NEXT_PUBLIC_SITE_URL` ve `NEXT_PUBLIC_SUPABASE_URL` gerçek public domainlerle uyumlu olmalıdır. Localhost değerleri production domaininde kullanılmamalıdır. - -### Supabase API Domaini Yayınlanmadı - -Tarayıcı Auth ve REST çağrıları için `NEXT_PUBLIC_SUPABASE_URL` değerine erişebilmelidir. Bu URL dışarıdan erişilemiyorsa login ve kayıt işlemleri çalışmaz. - diff --git a/content/07-dokploy-kurulum.md b/content/07-dokploy-kurulum.md deleted file mode 100644 index a3c0f48..0000000 --- a/content/07-dokploy-kurulum.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Dokploy Kurulumu -description: Neta'yı Dokploy üzerinde self-host etme adımları. -order: 7 ---- - -# Dokploy Kurulumu - -Dokploy üzerinde Neta'yı yayınlamak için önerilen yol full-stack Docker Compose kurulumudur. Bu kurulumda Neta, kendi PostgreSQL ve Supabase uyumlu servisleriyle birlikte çalışır. - -## Yeni Compose App Oluştur - -Dokploy panelinde yeni bir Compose app oluştur. - -Repository olarak Neta repository'sini seç ve Compose dosyası olarak şunu kullan: - -```text -docker-compose.full.yml -``` - -## Environment Hazırlığı - -Neta için gerekli env değerlerini üret: - -```bash -node scripts/generate-full-stack-env.mjs -``` - -Çıkan değerleri Dokploy environment bölümüne ekle. - -Production için özellikle şu değerleri düzenle: - -```env -NEXT_PUBLIC_SITE_URL=https://app.example.com -NEXT_PUBLIC_SUPABASE_URL=https://api.example.com -``` - -`JWT_SECRET`, `POSTGRES_PASSWORD`, `NEXT_PUBLIC_SUPABASE_ANON_KEY` ve `SUPABASE_SERVICE_ROLE_KEY` değerlerini gizli bilgi olarak sakla. - -## Servis Yönlendirmeleri - -Neta web uygulaması: - -```text -neta-web:3000 -``` - -Bundled Supabase API: - -```text -neta-supabase-proxy:8000 -``` - -olarak yönlendirilmelidir. - -Önerilen domain yapısı: - -```text -app.example.com -> neta-web:3000 -api.example.com -> neta-supabase-proxy:8000 -``` - -Bu yapı, tarayıcı tarafındaki Auth, REST ve Storage çağrılarının doğru proxy'ye gitmesini sağlar. - -## Deploy Süreci - -Dokploy deploy başlattığında: - -1. `neta-db` başlar. -2. Supabase Auth kendi tablolarını hazırlar. -3. Storage ve PostgREST servisleri başlar. -4. `neta-migrations` Neta SQL dosyalarını uygular. -5. Proxy healthy olduktan sonra web uygulaması başlar. - -Bu sıra Compose içindeki dependency kurallarıyla yönetilir. - -## İlk Admin Hesabı - -Deploy tamamlandıktan sonra: - -```text -https://app.example.com/register -``` - -sayfasını aç. - -İlk kullanıcı oluşturulduktan sonra kayıt ekranı kapanır. Daha sonra giriş için: - -```text -https://app.example.com/login -``` - -sayfası kullanılır. - -## Dokploy Sonrası Kontrol - -Şunları kontrol et: - -- Web domaini açılıyor mu? -- API domaininde `/health` endpointi cevap veriyor mu? -- İlk admin oluşturulabiliyor mu? -- Giriş yapılabiliyor mu? -- Dokploy servis loglarında migration hatası yok mu? - -API health kontrolü örneği: - -```text -https://api.example.com/health -``` - -## Güncelleme - -Yeni sürüme geçmeden önce yedek al: - -```bash -sh ./scripts/selfhost-backup.sh -``` - -Ardından Dokploy üzerinden yeni deploy başlat. - -## Dikkat Edilmesi Gerekenler - -- `docker-compose.yml` değil, full-stack kurulum için `docker-compose.full.yml` kullanılmalıdır. -- `NEXT_PUBLIC_SUPABASE_URL` dışarıdan erişilebilir olmalıdır. -- Service role key hiçbir zaman client tarafında paylaşılmamalıdır. -- PostgreSQL volume kalıcı olmalıdır. -- Storage volume kalıcı olmalıdır. - diff --git a/content/08-app-only-kurulum.md b/content/08-app-only-kurulum.md deleted file mode 100644 index af62b08..0000000 --- a/content/08-app-only-kurulum.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: App-Only Kurulum -description: Mevcut bir Supabase projesine bağlanarak Neta çalıştırma. -order: 8 ---- - -# App-Only Kurulum - -App-only kurulumda yalnızca Neta web uygulaması çalışır. Auth, veritabanı, REST API ve Storage servisleri mevcut bir Supabase projesinden sağlanır. - -Bu model, harici Supabase kullanmak isteyen veya mevcut Supabase altyapısına sahip kullanıcılar için uygundur. - -## Ne Zaman Kullanılır? - -App-only mod şu durumlarda tercih edilebilir: - -- Zaten aktif bir Supabase projen varsa -- Veritabanını managed servis olarak kullanmak istiyorsan -- Neta uygulamasını ayrı bir sunucuda yayınlamak istiyorsan -- Full-stack self-host yerine Supabase'in hosted altyapısını kullanmak istiyorsan - -İlk MVP için tam self-host hedefleniyorsa full-stack mod daha uygundur. - -## Gerekli Değerler - -App-only mod için gerekli environment değerleri: - -```env -NEXT_PUBLIC_SITE_URL=https://app.example.com -NEXT_PUBLIC_SUPABASE_URL=https://project-ref.supabase.co -NEXT_PUBLIC_SUPABASE_ANON_KEY=... -SUPABASE_SERVICE_ROLE_KEY=... -SUPABASE_INTERNAL_URL=https://project-ref.supabase.co -``` - -Migration çalıştırmak için ayrıca doğrudan PostgreSQL bağlantısı gerekir: - -```env -DATABASE_URL=postgresql://postgres:password@host:5432/postgres -``` - -## Migration'ları Uygula - -App-only modda migration dosyaları otomatik uygulanmaz. Neta'nın SQL dosyalarını bağlandığın Supabase projesinde çalıştırman gerekir. - -Repository kökünde: - -```bash -DATABASE_URL='postgresql://postgres:password@host:5432/postgres' sh ./scripts/apply-migrations.sh -``` - -Bu script şu dosyaları sırayla uygular: - -- `supabase/schema.sql` -- `supabase/migrations/0002_add_freelancer_os_core_tables.sql` -- `supabase/migrations/0003_add_project_planning_assets.sql` -- `supabase/migrations/0004_add_business_os_tables.sql` -- `supabase/migrations/0005_add_advanced_crm_tables.sql` -- `supabase/migrations/0006_add_pgvector_and_embeddings.sql` -- `supabase/migrations/0007_add_client_portal_tables.sql` -- `supabase/migrations/0008_add_project_progress_and_quota.sql` -- `supabase/migrations/0009_lock_registration_after_first_admin.sql` - -## Doğru Projeye Uyguladığından Emin Ol - -En önemli kural: - -```text -Migration hangi Supabase projesinde çalıştıysa uygulama da aynı projeye bağlanmalıdır. -``` - -Uygulama `NEXT_PUBLIC_SUPABASE_URL` değerindeki projeye istek atar. Migration farklı bir projede çalıştıysa `/register`, login veya veri işlemleri hata verebilir. - -## Docker ile Başlat - -App-only modda şu Compose dosyası kullanılır: - -```bash -docker compose up -d --build -``` - -Bu Compose dosyası sadece web uygulamasını çalıştırır ve harici Supabase değerlerini bekler. - -## `.env.local` Uyarısı - -Lokal geliştirme sırasında Next.js `.env.local` dosyasını okur. - -Eğer `.env.local` şu şekilde hosted Supabase'e bakıyorsa: - -```env -NEXT_PUBLIC_SUPABASE_URL=https://project-ref.supabase.co -``` - -lokal `pnpm dev` çalıştırdığında self-host Docker veritabanı değil bu hosted Supabase projesi kullanılır. - -Self-host Docker stack ile lokal geliştirme yapmak istiyorsan `.env.local` değerlerini buna göre düzenlemen gerekir. - -## İlk Admin - -Migrationlar doğru projede çalıştıktan sonra `/register` sayfası ilk admin oluşturmak için kullanılabilir. - -Eğer `is_first_admin_setup_available()` fonksiyonu `false` dönüyorsa, o projede zaten profil kaydı vardır ve kayıt kapalıdır. - diff --git a/content/09-ilk-admin-ve-kayit-kilidi.md b/content/09-ilk-admin-ve-kayit-kilidi.md deleted file mode 100644 index 4f1a659..0000000 --- a/content/09-ilk-admin-ve-kayit-kilidi.md +++ /dev/null @@ -1,127 +0,0 @@ ---- -title: İlk Admin ve Kayıt Kilidi -description: İlk admin hesabının oluşturulması ve kayıt sisteminin kilitlenmesi. -order: 9 ---- - -# İlk Admin ve Kayıt Kilidi - -Neta'nın MVP self-host modeli tek admin odaklıdır. Bu nedenle sistem ilk kurulumda bir admin hesabı oluşturulmasına izin verir ve bu hesap oluştuktan sonra public kayıt ekranını kapatır. - -Bu davranış, tek freelancer kullanımında daha güvenli ve kontrollü bir başlangıç sağlar. - -## İlk Admin Nasıl Oluşturulur? - -Temiz kurulumdan sonra şu sayfayı aç: - -```text -/register -``` - -Bu sayfada oluşturulan ilk kullanıcı Neta çalışma alanının admin kullanıcısı olarak kabul edilir. - -Kayıt tamamlandığında: - -- Supabase Auth içinde kullanıcı oluşur. -- `public.profiles` tablosunda profil kaydı oluşur. -- Kayıt kilidi aktif hale gelir. -- `/register` sayfası artık açık kalmaz. - -## Kayıt Neden Kapanır? - -Neta ilk MVP aşamasında public kullanıcı kaydını sürekli açık bırakmaz. Bunun sebepleri: - -- Tek freelancer kullanım modelini korumak -- Yetkisiz kullanıcı kaydını engellemek -- Self-host kurulumda basit ve güvenli başlangıç sağlamak -- Daha sonra eklenecek davet veya client portal akışlarını admin kontrollü yapmak - -## 0009 Migration Dosyası - -Kayıt kilidi şu migration ile eklenir: - -```text -supabase/migrations/0009_lock_registration_after_first_admin.sql -``` - -Bu migration: - -- `public.is_first_admin_setup_available()` fonksiyonunu ekler. -- `public.handle_new_user()` trigger fonksiyonunu günceller. -- İlk profil oluştuysa public signup işlemlerini engeller. -- Anon ve authenticated rollerine setup kontrol fonksiyonu için execute yetkisi verir. - -## `/register` Sayfasının Davranışı - -Temiz kurulumda: - -```text -/register -``` - -açılır ve ilk admin oluşturulabilir. - -İlk profil oluştuktan sonra: - -```text -/register -``` - -şu davranışı gösterir: - -```text -/login -``` - -sayfasına yönlendirir ve kayıt kapalı mesajı gösterir. - -Bu hata değil, beklenen güvenlik davranışıdır. - -## Migration Nerede Çalışmalı? - -Full-stack modda migration otomatik çalışır. - -```bash -docker compose -f docker-compose.full.yml up -d --build -``` - -komutu çalıştığında `neta-migrations` servisi gerekli SQL dosyalarını uygular. - -App-only modda ise migration bağlanılan Supabase projesinin veritabanında çalıştırılmalıdır: - -```bash -DATABASE_URL='postgresql://postgres:password@host:5432/postgres' sh ./scripts/apply-migrations.sh -``` - -## Hosted Supabase ve Self-Host Karışıklığı - -Lokal geliştirmede `.env.local` dosyası hosted Supabase projesine bakıyor olabilir. - -Örnek: - -```env -NEXT_PUBLIC_SUPABASE_URL=https://project-ref.supabase.co -``` - -Bu durumda `localhost` üzerinden çalışan Next.js uygulaması self-host Docker veritabanını değil, hosted Supabase projesini kullanır. - -Eğer migrationı Docker DB'de çalıştırıp uygulama hosted Supabase'e bağlıysa migration uygulamada görünmez. Tersi de geçerlidir. - -## Yaygın Mesajlar - -### Kayıt kapalı - -Bu mesaj, ilk admin veya profil kaydının zaten oluşturulduğunu gösterir. Giriş için `/login` kullanılmalıdır. - -### İlk kurulum kontrolü yapılamadı - -Bu mesaj, uygulamanın `is_first_admin_setup_available()` RPC fonksiyonunu çağırırken hata aldığını gösterir. - -Olası sebepler: - -- Migration yanlış Supabase projesinde çalıştırılmıştır. -- `0009` migration dosyası hiç çalıştırılmamıştır. -- Supabase bağlantı bilgileri yanlıştır. -- PostgREST schema cache henüz güncellenmemiştir. -- Uygulama `.env.local` üzerinden beklenmeyen bir projeye bağlanıyordur. - diff --git a/content/10-operasyon.md b/content/10-operasyon.md deleted file mode 100644 index 6e284bf..0000000 --- a/content/10-operasyon.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -title: Operasyon -description: Sağlık kontrolü, yedekleme ve geri yükleme işlemleri. -order: 10 ---- - -# Operasyon - -Neta self-host kurulumunda operasyonel bakımın temel başlıkları sağlık kontrolü, yedekleme, geri yükleme, log takibi ve güncelleme öncesi hazırlıktır. - -## Sağlık Kontrolü - -Full-stack kurulumda servislerin doğru çalıştığını kontrol etmek için: - -```bash -sh ./scripts/selfhost-doctor.sh -``` - -Bu script şunları doğrular: - -- Docker daemon erişilebilir mi? -- Gerekli containerlar çalışıyor mu? -- `neta-migrations` başarıyla tamamlandı mı? -- `neta-db` healthy durumda mı? -- `neta-web` healthy durumda mı? -- `neta-supabase-proxy` healthy durumda mı? -- Web health endpointi cevap veriyor mu? -- Supabase proxy health endpointi cevap veriyor mu? -- Auth settings endpointi çalışıyor mu? -- Neta tabloları veritabanında var mı? - -## Auth Smoke Test - -Gerçek Auth akışını test etmek için: - -```bash -NETA_DOCTOR_AUTH_SMOKE=1 sh ./scripts/selfhost-doctor.sh -``` - -Bu kontrol, temiz kurulumda signup ve password login akışını test eder. - -Dikkat: Temiz kurulumda bu işlem test kullanıcısı oluşturabilir. İlk admin hesabını manuel oluşturmak istiyorsan bu opsiyonu kullanmadan önce planlı hareket et. - -## Yedek Alma - -Full-stack modda yedek almak için: - -```bash -sh ./scripts/selfhost-backup.sh -``` - -Yedekler varsayılan olarak şu dizine yazılır: - -```text -./backups// -``` - -Yedek içeriği: - -- `postgres.dump` -- `storage.tar.gz` -- `manifest.txt` - -## Farklı Yedek Dizini Kullanma - -```bash -NETA_BACKUP_DIR=/path/to/backups sh ./scripts/selfhost-backup.sh -``` - -Bu yöntem, yedekleri ayrı bir disk veya mount üzerine yazmak için kullanılabilir. - -## Geri Yükleme - -Bir yedeği geri yüklemek için: - -```bash -sh ./scripts/selfhost-restore.sh ./backups/20260101T120000Z -``` - -Script geri yükleme öncesinde onay ister. - -Otomatik veya non-interactive geri yükleme için: - -```bash -NETA_RESTORE_FORCE=1 sh ./scripts/selfhost-restore.sh ./backups/20260101T120000Z -``` - -## Docker Volume Yapısı - -Full-stack modda kalıcı veriler Docker volume içinde tutulur: - -- `neta-db-data`: PostgreSQL verileri -- `neta-storage-data`: Storage dosyaları - -Bu volume'lar silinirse veriler kaybolur. - -Şu komut production ortamında dikkatli kullanılmalıdır: - -```bash -docker compose -f docker-compose.full.yml down -v -``` - -Çünkü `-v` parametresi volume'ları siler. - -## Log Takibi - -Servis loglarını görmek için: - -```bash -docker logs neta-web -docker logs neta-auth -docker logs neta-db -docker logs neta-migrations -docker logs neta-supabase-proxy -``` - -Kayıt, login veya migration sorunlarında özellikle şu loglar önemlidir: - -- `neta-auth` -- `neta-migrations` -- `neta-web` - -## Güncelleme Öncesi Kontrol Listesi - -Yeni sürüme geçmeden önce: - -1. Yedek al. -2. Yedek dosyalarının oluştuğunu kontrol et. -3. Mevcut `.env` dosyasını sakla. -4. Yeni sürüm notlarını oku. -5. Deploy sonrası `selfhost-doctor.sh` çalıştır. - -Önerilen akış: - -```bash -sh ./scripts/selfhost-backup.sh -git pull -docker compose -f docker-compose.full.yml up -d --build -sh ./scripts/selfhost-doctor.sh -``` - -## Production Notları - -MVP full-stack kurulum tek sunucu kullanımına uygundur. Kritik production ortamlarında ek olarak şunlar önerilir: - -- Düzenli harici yedek -- HTTPS -- Firewall -- Güçlü secret değerleri -- Sunucu disk izleme -- Log izleme -- Geri yükleme testleri - diff --git a/content/11-env-degiskenleri.md b/content/11-env-degiskenleri.md deleted file mode 100644 index b81d039..0000000 --- a/content/11-env-degiskenleri.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Ortam Değişkenleri -description: Neta kurulumunda kullanılan environment değişkenleri. -order: 11 ---- - -# Ortam Değişkenleri - -Neta kurulumunda environment değişkenleri uygulamanın hangi URL'leri kullanacağını, Supabase bağlantılarını, JWT secret değerlerini ve portları belirler. - -## Dosya Ayrımı - -Docker Compose: - -```text -.env -``` - -dosyasını kullanır. - -Lokal Next.js geliştirme: - -```text -.env.local -``` - -dosyasını kullanır. - -Bu ayrım önemlidir. `.env.local` hosted Supabase'e bakarken Docker full-stack farklı bir `.env` ile çalışıyor olabilir. - -## Full-Stack Değerleri - -Full-stack mod için env üretmek: - -```bash -node scripts/generate-full-stack-env.mjs > .env -``` - -Temel değişkenler: - -```env -NETA_INSTALL_MODE=full-stack -NEXT_PUBLIC_SITE_URL=http://localhost:3000 -NETA_PORT=3000 -NEXT_PUBLIC_SUPABASE_URL=http://localhost:8000 -SUPABASE_API_PORT=8000 -NEXT_PUBLIC_SUPABASE_ANON_KEY=... -SUPABASE_SERVICE_ROLE_KEY=... -JWT_SECRET=... -POSTGRES_PASSWORD=... -POSTGRES_PORT=54322 -JWT_EXPIRY=3600 -SMTP_ADMIN_EMAIL=admin@neta.local -``` - -## `NEXT_PUBLIC_SITE_URL` - -Neta uygulamasının public URL değeridir. - -Local örnek: - -```env -NEXT_PUBLIC_SITE_URL=http://localhost:3000 -``` - -Production örnek: - -```env -NEXT_PUBLIC_SITE_URL=https://app.example.com -``` - -Auth redirect ve site URL kontrollerinde kullanılır. - -## `NEXT_PUBLIC_SUPABASE_URL` - -Tarayıcıdan erişilebilen Supabase API URL değeridir. - -Full-stack local örnek: - -```env -NEXT_PUBLIC_SUPABASE_URL=http://localhost:8000 -``` - -Production örnek: - -```env -NEXT_PUBLIC_SUPABASE_URL=https://api.example.com -``` - -Bu URL dışarıdan erişilebilir olmalıdır. Tarayıcı Auth, REST ve Storage çağrıları için bu değeri kullanır. - -## `SUPABASE_INTERNAL_URL` - -Uygulama container içinden Supabase proxy'ye bağlanırken kullanılabilir. - -Full-stack Compose içinde varsayılan: - -```env -SUPABASE_INTERNAL_URL=http://neta-supabase-proxy:8000 -``` - -Bu değer genellikle manuel ayarlanmaz, Compose içinde verilir. - -## `NEXT_PUBLIC_SUPABASE_ANON_KEY` - -Supabase anon JWT değeridir. Client tarafında kullanılabilir, ama yine de doğru JWT secret ile üretilmiş olmalıdır. - -Full-stack modda script tarafından otomatik üretilir. - -## `SUPABASE_SERVICE_ROLE_KEY` - -Service role key yüksek yetkili bir anahtardır. - -Güvenlik kuralları: - -- Client tarafında paylaşılmamalıdır. -- Public repository'ye yazılmamalıdır. -- Sadece server-side işlemlerde kullanılmalıdır. -- Coolify/Dokploy gibi panellerde secret olarak saklanmalıdır. - -## `JWT_SECRET` - -Supabase Auth ve JWT doğrulama için kullanılan gizli değerdir. - -`NEXT_PUBLIC_SUPABASE_ANON_KEY` ve `SUPABASE_SERVICE_ROLE_KEY` bu secret ile uyumlu olmalıdır. Secret değişirse tokenlar da yeniden üretilmelidir. - -## `POSTGRES_PASSWORD` - -Bundled PostgreSQL için ana parola değeridir. - -Full-stack modda: - -- `neta-db` -- `neta-auth` -- `neta-rest` -- `neta-storage` -- `neta-migrations` - -servislerinin veritabanı bağlantılarında kullanılır. - -## Port Değerleri - -```env -NETA_PORT=3000 -SUPABASE_API_PORT=8000 -POSTGRES_PORT=54322 -``` - -Bu değerler host makinede hangi portların dışarı açılacağını belirler. - -Container içi portlar genellikle sabittir. - -## SMTP Değerleri - -MVP kurulumda e-posta doğrulama varsayılan olarak otomatik onaylıdır. Yine de ileride e-posta akışları için SMTP ayarları kullanılabilir. - -Örnek: - -```env -SMTP_ADMIN_EMAIL=admin@example.com -SMTP_HOST=smtp.example.com -SMTP_PORT=587 -SMTP_USER=... -SMTP_PASS=... -SMTP_SENDER_NAME=Neta -``` - -## App-Only Değerleri - -App-only modda minimum değerler: - -```env -NEXT_PUBLIC_SITE_URL=https://app.example.com -NEXT_PUBLIC_SUPABASE_URL=https://project-ref.supabase.co -NEXT_PUBLIC_SUPABASE_ANON_KEY=... -SUPABASE_SERVICE_ROLE_KEY=... -``` - -Migration için ayrıca: - -```env -DATABASE_URL=postgresql://postgres:password@host:5432/postgres -``` - -## Güvenlik Notları - -- `.env` ve `.env.local` dosyalarını commit etme. -- Service role key'i sadece sunucu tarafında kullan. -- Production ortamında güçlü secret değerleri kullan. -- Domain ve Supabase URL değerlerinin birbiriyle uyumlu olduğundan emin ol. -- Coolify/Dokploy panellerinde secret değerlerini public build loglarında göstermemeye dikkat et. - diff --git a/content/12-sorun-giderme.md b/content/12-sorun-giderme.md deleted file mode 100644 index f71785f..0000000 --- a/content/12-sorun-giderme.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Sorun Giderme -description: Kurulum ve çalışma sırasında karşılaşılan yaygın sorunlar. -order: 12 ---- - -# Sorun Giderme - -Bu bölüm, Neta kurulumu ve kullanımı sırasında sık karşılaşılabilecek sorunları açıklar. - -## `Database error finding user` - -Bu hata genellikle Supabase Auth servisinin Auth tablolarına doğru schema üzerinden erişemediğini gösterir. - -Full-stack modda beklenen çözüm: - -- `deploy/supabase/db/init.sh` içinde `supabase_auth_admin` rolünün `search_path` ayarı doğru olmalıdır. -- Temiz kurulumda Auth migrationları başarılı tamamlanmalıdır. -- `neta-auth` logları kontrol edilmelidir. - -Kontrol: - -```bash -docker logs neta-auth -``` - -Temiz kurulum için: - -```bash -docker compose -f docker-compose.full.yml down -v -docker compose -f docker-compose.full.yml up -d --build -``` - -Production ortamında `down -v` kullanmadan önce yedek alınmalıdır. - -## `Database error querying schema` - -Bu hata da çoğunlukla Auth schema veya migration state problemiyle ilgilidir. - -Kontrol edilmesi gerekenler: - -- `neta-auth` migrationları başarıyla tamamlandı mı? -- `auth.users` tablosu var mı? -- `auth.identities` tablosu var mı? -- Auth rolü doğru schema path ile çalışıyor mu? - -Full-stack kurulumda bu yapı otomatik hazırlanmalıdır. - -## `İlk kurulum kontrolü yapılamadı` - -Bu mesaj, uygulamanın şu RPC fonksiyonunu çağırırken hata aldığını gösterir: - -```text -public.is_first_admin_setup_available() -``` - -Olası sebepler: - -- `0009_lock_registration_after_first_admin.sql` çalışmamıştır. -- Migration yanlış Supabase projesinde çalışmıştır. -- Uygulama `.env.local` üzerinden farklı Supabase projesine bağlanıyordur. -- PostgREST schema cache güncel değildir. -- Supabase bağlantı bilgileri hatalıdır. - -Full-stack modda migration otomatik uygulanır. App-only modda migrationı doğru hosted Supabase projesinde çalıştırman gerekir. - -## `/register` Kayıt Kapalı Diyor - -Bu her zaman hata değildir. - -Eğer ilk admin veya herhangi bir profil kaydı zaten varsa `/register` kapanır ve `/login` sayfasına yönlendirir. - -Kontrol mantığı: - -```sql -select public.is_first_admin_setup_available(); -``` - -`false` dönüyorsa kayıt kapalıdır. - -## Migration Yanlış DB'de Çalıştı - -Bu sık yapılan bir hatadır. - -Örnek senaryo: - -- Docker full-stack DB'de migration çalıştırdın. -- Ama `.env.local` hosted Supabase projesine bakıyor. -- Uygulama hosted Supabase'e bağlandığı için Docker DB'deki migration görünmez. - -Çözüm: - -- Uygulamanın hangi Supabase URL'ye bağlandığını kontrol et. -- Migrationı aynı projenin veritabanında çalıştır. -- Full-stack test için `.env` ve `docker-compose.full.yml` kullan. - -## Docker Daemon Kapalı - -Hata örneği: - -```text -Cannot connect to the Docker daemon -``` - -Çözüm: - -- Docker Desktop'ı başlat. -- Linux sunucuda Docker servisinin çalıştığını kontrol et: - -```bash -sudo systemctl status docker -``` - -Başlatmak için: - -```bash -sudo systemctl start docker -``` - -## Port Çakışması - -Eğer `3000`, `8000` veya `54322` portları doluysa Compose başlatılamayabilir. - -`.env` içinde portları değiştir: - -```env -NETA_PORT=3010 -SUPABASE_API_PORT=8010 -POSTGRES_PORT=54323 -``` - -Sonra yeniden başlat: - -```bash -docker compose -f docker-compose.full.yml up -d --build -``` - -## `.env.local` Hosted Supabase'e Bakıyor - -Lokal geliştirme sırasında `pnpm dev` çalıştırırsan Next.js `.env.local` dosyasını okur. - -Eğer `.env.local` içinde şu varsa: - -```env -NEXT_PUBLIC_SUPABASE_URL=https://project-ref.supabase.co -``` - -uygulama hosted Supabase'e bağlanır. - -Self-host Docker stack için lokal geliştirme yapmak istiyorsan `.env.local` değerlerini self-host API URL'lerine göre düzenle. - -## Coolify veya Dokploy Env Eksikleri - -Compose dosyası bazı env değerleri eksikse bilinçli olarak fail-fast davranır. - -Örnek: - -```text -Set NEXT_PUBLIC_SUPABASE_URL in .env -``` - -Çözüm: - -- Environment panelinde tüm zorunlu değerleri gir. -- `NEXT_PUBLIC_SITE_URL` ve `NEXT_PUBLIC_SUPABASE_URL` değerlerinin production domainleriyle uyumlu olduğundan emin ol. - -## Health Check Başarısız - -Çalıştır: - -```bash -sh ./scripts/selfhost-doctor.sh -``` - -Hangi kontrolün failed olduğunu incele. - -Sık sebepler: - -- Migration runner tamamlanmamıştır. -- Proxy henüz healthy olmamıştır. -- Veritabanı başlamamıştır. -- Yanlış env değerleri kullanılmıştır. - -## Build Hatası - -Build için: - -```bash -pnpm build -``` - -Docker build için: - -```bash -docker compose -f docker-compose.full.yml up -d --build -``` - -Build sırasında environment kaynaklı hata alırsan `.env` ve Compose env değerlerini kontrol et. - diff --git a/content/13-guvenlik-ve-sinirlar.md b/content/13-guvenlik-ve-sinirlar.md deleted file mode 100644 index bd7d524..0000000 --- a/content/13-guvenlik-ve-sinirlar.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Güvenlik ve Sınırlar -description: MVP self-host modelinin güvenlik yaklaşımı ve mevcut sınırları. -order: 13 ---- - -# Güvenlik ve Sınırlar - -Neta'nın ilk self-host MVP sürümü tek freelancer kullanımına göre tasarlanmıştır. Güvenlik yaklaşımı basit, anlaşılır ve self-host edilebilir bir model üzerine kuruludur. - -## Tek Admin Modeli - -İlk kurulumda yalnızca bir admin hesabı oluşturulur. İlk admin hesabı oluştuğunda public kayıt ekranı kapanır. - -Bu yaklaşım: - -- Yetkisiz kayıtları engeller. -- Self-host kurulumda basit güvenlik modeli sağlar. -- Freelancer odaklı tek kullanıcı senaryosuna uygundur. - -Çoklu ekip veya çoklu rol yapısı MVP kapsamının dışındadır. - -## Public Signup Kilidi - -Kayıt kilidi sadece UI seviyesinde değildir. Veritabanı trigger fonksiyonu da ilk profil oluştuktan sonra public signup denemelerini engeller. - -Bu sayede biri doğrudan Supabase Auth signup endpointine istek atsa bile veritabanı seviyesinde kayıt engellenir. - -## Service Role Key Güvenliği - -`SUPABASE_SERVICE_ROLE_KEY` yüksek yetkili bir anahtardır. - -Kurallar: - -- Client tarafında kullanılmamalıdır. -- Public repository'ye eklenmemelidir. -- Loglarda gösterilmemelidir. -- Sadece server-side işlemlerde kullanılmalıdır. -- Coolify/Dokploy içinde secret olarak saklanmalıdır. - -Bu key sızarsa veritabanı üzerinde yüksek yetkili işlemler yapılabilir. - -## Row Level Security - -Neta tablolarında Row Level Security politikaları kullanılır. Amaç, kullanıcı verilerinin veritabanı seviyesinde de izole edilmesidir. - -MVP tek admin modeliyle çalışsa bile RLS yapısının korunması önemlidir. Gelecekte client portal, davet ve daha gelişmiş kullanıcı akışları bu temel üzerine genişletilebilir. - -## JWT Secret - -`JWT_SECRET`, Supabase Auth tokenlarının imzalanması için kullanılır. - -Bu secret değişirse: - -- Mevcut tokenlar geçersiz hale gelebilir. -- Anon key ve service role key yeniden üretilmelidir. - -Production ortamında güçlü ve rastgele bir secret kullanılmalıdır. - -## Storage Sınırları - -Full-stack MVP kurulumda Storage lokal disk backend ile çalışır. - -Bu yapı: - -- Tek sunucu kullanımına uygundur. -- Basit backup/restore akışı sağlar. -- Harici storage servisi gerektirmez. - -Ancak yüksek ölçekli production ortamlarında S3 uyumlu harici storage daha uygun olabilir. - -## Yedekleme Sorumluluğu - -Self-host kurulumda veri sorumluluğu kullanıcıdadır. - -Düzenli yedek alınmalıdır: - -```bash -sh ./scripts/selfhost-backup.sh -``` - -Yedekler mümkünse aynı sunucu dışında da saklanmalıdır. - -## HTTPS ve Ağ Güvenliği - -Production ortamında: - -- HTTPS kullanılmalıdır. -- PostgreSQL portu public internete açılmamalıdır. -- Sadece gerekli portlar dışarı açılmalıdır. -- Sunucu firewall kuralları düzenlenmelidir. -- Admin panel ve deploy panel erişimleri korunmalıdır. - -## SMTP ve E-posta - -MVP kurulumda e-posta doğrulama otomatik onaylı olabilir. Production ortamında e-posta akışları kullanılacaksa SMTP ayarları yapılmalıdır. - -SMTP ayarları olmadan bazı e-posta tabanlı Auth akışları beklenen şekilde çalışmayabilir. - -## Mevcut Sınırlar - -İlk MVP self-host sürümünde şu alanlar sınırlıdır: - -- Çoklu ekip yönetimi -- Gelişmiş rol ve izin sistemi -- Çok tenantlı SaaS modeli -- Otomatik scheduled backup -- Harici S3 storage entegrasyonu -- High availability kurulum -- Gelişmiş audit log sistemi -- Kurumsal SSO - -Bu sınırlar, ilk sürümün sade, kurulabilir ve freelancer odaklı kalmasını sağlar. - -## Gelecek Genişletme Alanları - -İlerleyen fazlarda şu alanlar geliştirilebilir: - -- Admin kontrollü kullanıcı davetleri -- Client portal kullanıcı yönetimi -- Takım üyeleri ve roller -- S3 uyumlu storage -- Otomatik backup planlama -- Daha gelişmiş gözlemleme ve loglama -- SMTP ve e-posta şablonları -- Import/export araçları - -Neta'nın self-host temeli bu genişletmeler için uygun bir başlangıç sağlar. -