Documentación/Guía de self-hosting

Guía de self-hosting

Ejecuta VibeBasket en tu propia infraestructura con la forma de despliegue de nodo único para la que el producto está optimizado: un proceso de app, una base SQLite, OAuth opcional y almacenamiento de backup cifrado opcional.

Docker (recomendado)

Es la forma más sencilla de autoalojar VibeBasket. La imagen usa una build multi-stage ligera basada en Node.js 22 Alpine. El archivo SQLite se persiste en un volumen Docker con nombre para que los datos sobrevivan a reinicios y actualizaciones del contenedor.

Paso 1 — Clonar y configurar

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

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

Paso 2 — Arrancar con Docker Compose

docker compose up -d

# View logs
docker compose logs -f web

Paso 3 — Poblar el catálogo

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

Actualización

git pull
docker compose up -d --build

Helm (Kubernetes)

Hay un chart Helm completo en charts/vibebasket/. El chart despliega un Deployment de una sola réplica con Service ClusterIP, Ingress opcional y un PersistentVolumeClaim para la base SQLite. Los valores no secretos van bajo .Values.env, mientras que secretos como AUTH_SECRET y los OAuth client secrets deben ir en .Values.secretEnv o en un Kubernetes Secret existente.

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

Instalación manual

Requiere Node.js >=20 y pnpm >=9. Adecuado para VMs, servidores bare-metal o plataformas que no ejecutan 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

Variables de entorno

URLs de callback OAuth

Al habilitar autenticación OAuth, configura la URL exacta de callback de redirección en la consola de desarrollador de cada proveedor:

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

Para desarrollo local, sustituye ${NEXTAUTH_URL} por http://localhost:3000.

No hagas commit de tu archivo .env . .env .gitignore. En despliegues Docker, pasa los secretos como variables de entorno o usa Docker secrets.

Si ejecutas VibeBasket detrás de Cloudflare, mantén activas las cabeceras de seguridad de la aplicación y desactiva las funciones edge que inyectan scripts para este sitio salvo que las tengas contempladas explícitamente. En la práctica, eso significa apagar Browser Insights, Rocket Loader y Speed Brain / speculative prefetch, ya que inyectan scripts inline o de terceros y provocarían violaciones CSP por diseño.

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

TTL del bundle y limpieza

Los bundles anónimos caducan a las 48 horas. Los bundles de usuarios registrados duran 365 días. La plataforma purga periódicamente bundles caducados y tokens de sesión obsoletos. Los administradores pueden lanzar una limpieza forzada manual desde System Health en el panel admin.

Panel admin

El panel admin en /admin ofrece controles de sync del catálogo, gestión de backups, chequeos de salud del índice FTS5, diagnósticos de integridad de base de datos, utilidades de limpieza forzada, telemetría general de usuarios y configuración de correos admin. El acceso está controlado por la variable de entorno ADMIN_OAUTH_EMAILS .

Despliegue con Helm

Hay un chart Helm disponible en charts/vibebasket/ para despliegues en Kubernetes. Incluye Deployment, Service, Ingress y PersistentVolumeClaim para el almacenamiento SQLite.

$ helm install vibebasket ./charts/vibebasket \

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

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

El despliegue usa strategy: Recreate para evitar corrupción de SQLite durante actualizaciones. El securityContext del pod se ejecuta como usuario no root 1001 con todas las capacidades retiradas. Los secretos de producción deberían inyectarse mediante existingSecret en lugar de incrustarse en values.

Antes de exponer un dominio público, recorre la checklist de preparación para producción del repositorio en docs/PRODUCTION_READINESS_CHECKLIST.md.

Modo WAL de SQLite

VibeBasket habilita el modo SQLite WAL (Write-Ahead Logging) al arrancar. Esto permite lecturas concurrentes durante escrituras y es necesario para la sincronización del catálogo. No montes el archivo de base de datos en un sistema de archivos de red (NFS, CIFS), porque el bloqueo WAL depende de primitivas locales del sistema operativo. Si ejecutas varias réplicas de Node.js, usa un balanceador que dirija todas las escrituras a una sola instancia o migra a una base remota como Turso.