Dokümanlar/Self-Hosting Rehberi

Self-Hosting Rehberi

VibeBasket’i kendi altyapında, ürünün şu anda optimize edildiği tek düğümlü dağıtım şekliyle çalıştır: tek uygulama süreci, tek SQLite veritabanı, isteğe bağlı OAuth ve isteğe bağlı şifreli backup storage.

Docker (önerilen)

VibeBasket’i self-host etmek için en kolay yol budur. İmaj, Node.js 22 Alpine tabanlı hafif bir multi-stage build kullanır. SQLite veritabanı dosyası isimlendirilmiş bir Docker volume üzerinde tutulur; böylece veri, container yeniden başlatmaları ve güncellemeler sırasında korunur.

Adım 1 — Klonla ve yapılandır

git clone https://github.com/mhmtayberk/VibeBasket.git
cd VibeBasket

# Copy the example env file and fill in your values
cp .env.example .env

Adım 2 — Docker Compose ile başlat

docker compose up -d

# View logs
docker compose logs -f web

Adım 3 — Kataloğu seed et

# Run the catalog sync inside the running container
docker compose exec web node scripts/catalog-sync.mjs

Güncelleme

git pull
docker compose up -d --build

Helm (Kubernetes)

Tam özellikli Helm chart’ı charts/vibebasket/ içinde bulunur. Chart; SQLite veritabanı için tek replikalı Deployment, ClusterIP Service, isteğe bağlı Ingress ve bir PersistentVolumeClaim kurar. Secret olmayan çalışma zamanı değerleri .Values.env altında, AUTH_SECRET ve OAuth client secret’ları gibi hassas değerler ise .Values.secretEnv altında veya mevcut bir Kubernetes Secret içinde tutulmalıdır.

git clone https://github.com/mhmtayberk/VibeBasket.git
cd VibeBasket

helm install vibebasket ./charts/vibebasket \
  --set env.NEXTAUTH_URL=https://vibebasket.example.com \
  --set secretEnv.AUTH_SECRET=$(openssl rand -base64 32) \
  --set env.AUTH_GITHUB_ID=your-client-id \
  --set secretEnv.AUTH_GITHUB_SECRET=your-client-secret \
  --set env.AUTH_GITHUB_ENABLED=true \
  --set persistence.size=5Gi

# Or install with a custom values file
helm install vibebasket ./charts/vibebasket -f my-values.yaml

Manuel Kurulum

Node.js >=20 ve pnpm >=9 gerektirir. VM’ler, bare-metal sunucular veya Docker çalıştırmayan platformlar için uygundur.

git clone https://github.com/mhmtayberk/VibeBasket.git && cd VibeBasket
cp .env.example .env          # fill in values (see below)
pnpm install --frozen-lockfile
pnpm run build
node scripts/catalog-sync.mjs # seed the database
pnpm --filter web start        # production server on :3000

Ortam Değişkenleri

OAuth Callback URL’leri

OAuth kimlik doğrulamasını açarken, her sağlayıcının geliştirici panelinde tam redirect callback URL’ini yapılandırmalısın:

GitHub

${NEXTAUTH_URL}/api/auth/callback/github

Google

${NEXTAUTH_URL}/api/auth/callback/google

Apple

${NEXTAUTH_URL}/api/auth/callback/apple

Microsoft Entra ID

${NEXTAUTH_URL}/api/auth/callback/microsoft-entra-id

Yerel geliştirme için ${NEXTAUTH_URL} yerine http://localhost:3000 kullan.

.env dosyanı asla commit etme. .env .gitignore içinde listelenmiştir. Docker dağıtımlarında secret’ları ortam değişkeni olarak geç veya Docker secrets kullan.

VibeBasket’i Cloudflare arkasında çalıştırıyorsan uygulama güvenlik başlıklarını açık tut ve özellikle planlamadığın sürece bu site için script enjekte eden edge özelliklerini kapat. Pratikte bu; Browser Insights, Rocket Loader ve inline ya da üçüncü taraf script ekleyen Speed Brain / speculative prefetch özelliklerini devre dışı bırakmak anlamına gelir. Aksi halde site tasarım gereği CSP ihlalleri loglar.

Değişken	Zorunlu	Açıklama
DATABASE_URL	Zorunlu	SQLite connection string. Use file:/data/vibebasket.db for Docker (volume mount) or an absolute path for manual installs.
AUTH_SECRET	Zorunlu	Random 32-byte secret used to sign Next-Auth session tokens. Generate with: openssl rand -base64 32
NEXTAUTH_URL	Zorunlu	The public canonical URL of your deployment, e.g. https://vibebasket.example.com. Required for OAuth redirects.
AUTH_TRUST_HOST	İsteğe bağlı	Set to true when running behind a reverse proxy such as Coolify, Nginx, or Cloudflare. Strongly recommended for production OAuth callback reliability.
AUTH_GITHUB_ID / SECRET	İsteğe bağlı	GitHub OAuth App credentials. Set AUTH_GITHUB_ENABLED=true to enable.
AUTH_GOOGLE_ID / SECRET	İsteğe bağlı	Google OAuth credentials. Set AUTH_GOOGLE_ENABLED=true to enable.
AUTH_APPLE_ID / SECRET	İsteğe bağlı	Apple Sign-In credentials. Set AUTH_APPLE_ENABLED=true to enable.
AUTH_MICROSOFT_ENTRA_ID_ID / SECRET	İsteğe bağlı	Microsoft Entra ID (Azure AD) credentials. Set AUTH_MICROSOFT_ENTRA_ID_ENABLED=true. Uses /common/ endpoint by default.
ADMIN_OAUTH_EMAILS	İsteğe bağlı	Comma-separated list of admin emails. Access is granted only when the OAuth account email is allowlisted and verified.
TRUST_PROXY	İsteğe bağlı	Set to true when running behind Cloudflare, Nginx, or another trusted reverse proxy. Proxy IP headers are ignored otherwise.
CATALOG_REFRESH_TOKEN	İsteğe bağlı	Optional token required for authenticated production callers that use /api/catalog?refresh=1.
BACKUP_STORAGE_BACKEND	İsteğe bağlı	Backup storage backend: local, s3, r2, spaces, azure, or gcs. Defaults to local. Can also be set via admin panel.
BACKUP_S3_* / R2_* / SPACES_*	İsteğe bağlı	S3-compatible storage credentials (endpoint, region, bucket, access key, secret key). Covers AWS S3, Cloudflare R2, and DigitalOcean Spaces.
BACKUP_AZURE_CONNECTION_STRING / CONTAINER	İsteğe bağlı	Azure Blob Storage connection string and container name.
BACKUP_GCS_BUCKET / PROJECT_ID	İsteğe bağlı	Google Cloud Storage bucket name and GCP project ID.

Bundle TTL & Temizlik

Anonim bundle’lar 48 saat sonra sona erer. Kayıtlı kullanıcı bundle’ları 365 gün boyunca kalır. Platform süresi dolan bundle’ları ve eski session token’larını periyodik olarak temizler. Yöneticiler, Admin Panel içindeki System Health bölümünden manuel force cleanup tetikleyebilir.

Admin Panel

/admin üzerindeki yönetim paneli; katalog senkronu kontrolleri, yedek yönetimi, FTS5 indeks sağlık kontrolleri, veritabanı bütünlük tanıları, force cleanup yardımcıları, kullanıcı genel görünümü telemetrisi ve yönetici e-posta yapılandırmasını sunar. Erişim, ADMIN_OAUTH_EMAILS ortam değişkeniyle korunur.

Helm Dağıtımı

Kubernetes dağıtımları için charts/vibebasket/ altında bir Helm chart bulunur. Chart; SQLite depolaması için Deployment, Service, Ingress ve PersistentVolumeClaim içerir.

$ helm install vibebasket ./charts/vibebasket \

--set env.NEXTAUTH_URL=https://vibebasket.example.com \

--set secretEnv.AUTH_SECRET=<generated-secret>

Dağıtım, güncellemeler sırasında SQLite bozulmasını önlemek için strategy: Recreate kullanır. Pod securityContext , tüm yetkiler düşürülmüş şekilde root olmayan 1001 kullanıcısıyla çalışır. Production secret’ları values içine gömmek yerine existingSecret ile verilmelidir.

Genel erişime açmadan önce depodaki docs/PRODUCTION_READINESS_CHECKLIST.md kontrol listesini adım adım gözden geçir.

SQLite WAL Modu

VibeBasket başlangıçta SQLite WAL (Write-Ahead Logging) modunu etkinleştirir. Bu sayede yazma sırasında eşzamanlı okumalar mümkün olur ve katalog senkronu için gereklidir. WAL kilitlemesi yerel işletim sistemi ilkelere dayandığından veritabanı dosyasını ağ dosya sistemi (NFS, CIFS) üzerine bağlama. Birden fazla Node.js replikası çalıştırıyorsan tüm yazmaları tek örneğe yönlendiren bir load balancer kullan veya Turso gibi uzak bir veritabanına geç.