Документация/Гайд по self-hosting

Гайд по self-hosting

Запускайте VibeBasket в собственной инфраструктуре в той single-node deployment-схеме, под которую сейчас лучше всего оптимизирован продукт: один app process, одна SQLite database, optional OAuth и optional encrypted backup storage.

Docker (рекомендуется)

Это самый простой способ self-host’ить VibeBasket. Образ использует лёгкий multi-stage build на базе Node.js 22 Alpine. SQLite database file хранится в named Docker volume, поэтому данные переживают restart контейнера и upgrade.

Шаг 1 — Клонируйте и настройте

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 — Засейдите каталог

# 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)

Полноценный Helm chart доступен в charts/vibebasket/. Chart разворачивает single-replica Deployment с ClusterIP Service, optional Ingress и PersistentVolumeClaim для SQLite database. Несекретные runtime values должны храниться в .Values.env, а такие секреты, как AUTH_SECRET и OAuth client secrets, — в .Values.secretEnv или в существующем 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. Подходит для VM, bare-metal серверов и платформ, где 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-аутентификации настройте точный redirect callback URL в developer console каждого провайдера:

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

Для локальной разработки замените ${NEXTAUTH_URL} на http://localhost:3000.

Никогда не коммитьте файл .env . Он уже добавлен в .gitignore. В Docker deployment’ах передавайте secrets как environment variables или используйте Docker secrets..env .gitignore. В Docker deployment’ах передавайте secrets как environment variables или используйте Docker secrets.

Если вы запускаете VibeBasket за Cloudflare, оставьте application security headers включёнными и выключите edge-функции, которые внедряют скрипты, если только вы специально не проектировали совместимость с ними. На практике это означает отключить Browser Insights, Rocket Loader и Speed Brain / speculative prefetch, так как они добавляют inline или third-party scripts и по дизайну вызывают CSP violations.

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

Bundle TTL и cleanup

Анонимные bundle’ы истекают через 48 часов. Bundle’ы зарегистрированных пользователей живут 365 дней. Платформа периодически очищает expired bundles и stale session tokens. Администраторы могут вручную запустить force cleanup из раздела System Health в админке.

Админ-панель

Админ-панель на /admin предоставляет control’ы для sync каталога, backup management, проверки здоровья FTS5 index, диагностики целостности базы, force cleanup utilities, user telemetry overview и конфигурации admin email. Доступ защищён через переменную окружения ADMIN_OAUTH_EMAILS .

Helm deployment

Для Kubernetes deployment’ов доступен Helm chart в charts/vibebasket/ . Он включает Deployment, Service, Ingress и PersistentVolumeClaim для SQLite storage.

$ helm install vibebasket ./charts/vibebasket \

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

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

Deployment использует strategy: Recreate , чтобы избежать SQLite corruption во время обновлений. Pod securityContext работает от non-root user 1001 с удалёнными capabilities. Production secrets лучше передавать через existingSecret , а не встраивать в values.

Перед публикацией публичного домена пройдите checklist production readiness из docs/PRODUCTION_READINESS_CHECKLIST.md.

SQLite WAL mode

VibeBasket включает SQLite WAL (Write-Ahead Logging) mode при запуске. Это позволяет читать данные во время записи и необходимо для процесса sync каталога. Не размещайте database file на network filesystem (NFS, CIFS), потому что WAL locking опирается на локальные OS primitives. Если вы запускаете несколько реплик Node.js, используйте load balancer, который направляет все writes в один instance, или мигрируйте на удалённую базу вроде Turso.