दस्तावेज़/सेल्फ-होस्टिंग गाइड

सेल्फ-होस्टिंग गाइड

VibeBasket को अपनी infrastructure पर उसी single-node deployment shape में चलाएँ जिसके लिए product अभी optimized है: एक app process, एक SQLite database, optional OAuth, और optional encrypted backup storage.

Docker (अनुशंसित)

VibeBasket को self-host करने का सबसे आसान तरीका यही है। Image, Node.js 22 Alpine पर आधारित lean multi-stage build का उपयोग करती है। SQLite database file एक named Docker volume में persist होती है, इसलिए container restart या upgrade के बाद भी data सुरक्षित रहता है।

स्टेप 1 — Clone और configure करें

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

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

स्टेप 2 — Docker Compose के साथ शुरू करें

docker compose up -d

# View logs
docker compose logs -f web

स्टेप 3 — Catalog seed करें

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

अपग्रेड करना

git pull
docker compose up -d --build

Helm (Kubernetes)

charts/vibebasket/ में एक fully-featured Helm chart उपलब्ध है। यह chart single-replica Deployment, ClusterIP Service, optional Ingress, और SQLite database के लिए PersistentVolumeClaim deploy करता है। Non-secret runtime values को .Values.env में, जबकि AUTH_SECRET और OAuth client secrets जैसे secrets को .Values.secretEnv या existing Kubernetes Secret में रखना चाहिए।

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

मैनुअल इंस्टॉलेशन

Node.js >=20 और pnpm >=9 की आवश्यकता है। यह VMs, bare-metal servers, या उन platforms के लिए उपयुक्त है जहाँ Docker नहीं चलता।

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

एनवायरनमेंट वैरिएबल्स

OAuth callback URLs

OAuth authentication सक्षम करते समय, हर provider के developer console में exact redirect callback URL कॉन्फ़िगर करें:

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

Local development के लिए ${NEXTAUTH_URL} को http://localhost:3000 से बदलें।

अपनी .env file को कभी commit न करें। .env .gitignore में शामिल है। Docker deployments में secrets को environment variables के रूप में पास करें या Docker secrets का उपयोग करें।

यदि आप VibeBasket को Cloudflare के पीछे चला रहे हैं, तो application security headers चालू रखें और इस साइट के लिए script inject करने वाले edge features को बंद रखें, जब तक कि आपने उनके लिए स्पष्ट रूप से योजना न बनाई हो। व्यवहार में इसका मतलब है Browser Insights, Rocket Loader और Speed Brain / speculative prefetch जैसी सुविधाएँ बंद करना, क्योंकि वे inline या third-party scripts inject करती हैं और अन्यथा साइट CSP violations log करेगी।

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

Bundle TTL और cleanup

Anonymous bundles 48 घंटे बाद expire हो जाते हैं। Registered users के bundles 365 दिनों तक बने रहते हैं। Platform समय-समय पर expired bundles और stale session tokens को purge करता है। Administrators System Health के अंतर्गत admin dashboard से manual force cleanup चला सकते हैं।

एडमिन डैशबोर्ड

/admin पर मौजूद admin panel catalog sync controls, backup management, FTS5 index health checks, database integrity diagnostics, force cleanup utilities, user overview telemetry और admin email configuration प्रदान करता है। Access, ADMIN_OAUTH_EMAILS environment variable द्वारा नियंत्रित है।

Helm deployment

Kubernetes deployments के लिए charts/vibebasket/ में Helm chart उपलब्ध है। इसमें SQLite storage के लिए Deployment, Service, Ingress और PersistentVolumeClaim शामिल हैं।

$ helm install vibebasket ./charts/vibebasket \

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

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

Deployment, updates के दौरान SQLite corruption रोकने के लिए strategy: Recreate का उपयोग करता है। Pod securityContext non-root user 1001 के रूप में चलता है और सभी capabilities हटाई जाती हैं। Production secrets को values में embed करने के बजाय existingSecret के माध्यम से देना चाहिए।

Public domain expose करने से पहले repository की docs/PRODUCTION_READINESS_CHECKLIST.md में दी गई production readiness checklist पूरी करें।

SQLite WAL mode

VibeBasket startup पर SQLite WAL (Write-Ahead Logging) mode सक्षम करता है। इससे writes के दौरान concurrent reads संभव होती हैं और catalog sync प्रक्रिया के लिए यह आवश्यक है। Database file को network filesystem (NFS, CIFS) पर mount न करें, क्योंकि WAL locking local OS primitives पर निर्भर करती है। यदि आप multiple Node.js replicas चलाते हैं, तो load balancer का उपयोग करें जो सभी writes को एक ही instance तक route करे, या Turso जैसी remote database पर migrate करें।