ElVendedorDocs

Despliegue del backend

Instala y configura el backend Laravel de ElVendedor: PHP, base de datos, migraciones, colas, cron, sync y licencias.

Para implementadores4 min de lecturaActualizado el 16 de noviembre de 2026

El backend es una aplicación Laravel 12 (Inertia + Vue) que además expone la API v1 de sincronización, licencias y marketplace. Al terminar esta página tendrás el servicio en marcha con su base de datos, tareas programadas, cola y política de compatibilidad, y sabrás cómo verificar que responde.

Antes de empezar

Requisito Dato del repositorio
PHP ^8.2 (el entorno de referencia usa 8.4.5)
Base de datos SQLite por defecto, MySQL soportado
Composer Sí, con composer.lock versionado
Node y npm Para compilar el frontend del backoffice con Vite 7
Servidor web Con HTTPS y cabeceras forwarded; el host de referencia es Laravel Cloud
Cron Necesario para el scheduler de Laravel
Cola QUEUE_CONNECTION=database: hace falta un worker

Instalación de dependencias

composer.json incluye un script setup que hace el arranque completo:

composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --force
npm install
npm run build

Ese es el orden real del script (también ejecutable como composer run setup). En un servidor de producción conviene revisar .env antes de migrar: si la base de datos o el APP_KEY están mal, la migración y las sesiones salen mal.

Variables de entorno mínimas

APP_NAME=ElVendedor
APP_VERSION=2.1.6
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:...
APP_URL=https://mi-servidor.example
CORS_ALLOWED_ORIGINS=

DB_CONNECTION=sqlite        # o mysql con DB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD
SESSION_DRIVER=database
QUEUE_CONNECTION=database
CACHE_STORE=database
FILESYSTEM_DISK=local

APP_VERSION es la versión de referencia que el bootstrap anuncia como compatibility.server_app_version. APP_KEY vacío rompe el cifrado, las sesiones y la firma del estado de licencia: genera una y guárdala fuera del repositorio.

Base de datos

El repositorio trae 86 migraciones y seis seeders (DatabaseSeeder, BusinessSeeder, CatalogDemoSeeder, MarketplaceCategorySeeder, MarketplaceCurrencySeeder, SupremeAdminSeeder). En un cliente real:

php artisan migrate --force
  • migrate:fresh --seed es solo para entornos locales (borra todo).
  • Las credenciales de demo (owner@example.com / password) nunca deben existir en producción.
  • Nunca versiones *.sqlite, dumps ni .env: el repositorio ya ignora *.sqlite y la comprobación es git ls-files '*.sqlite', que debe salir vacía.

Colas y tareas programadas

routes/console.php declara tres comandos: sync:prune-events --days=180 (semanal, domingo 03:00), inventory:expire-reservations (cada cinco minutos) y licensing:expire (diaria). Todos usan onOneServer() y withoutOverlapping().

  • El host debe invocar el scheduler cada minuto (php artisan schedule:run). La línea exacta de cron o el plan del hosting no están documentados en el repositorio.
  • La cola usa la base de datos, así que necesitas un worker permanente. El comando de referencia del repo es php artisan queue:listen --tries=1 --timeout=0.

Sincronización

config/sync.php se alimenta de estas variables:

Variable Por defecto Uso
SYNC_PROTOCOL_VERSION 1 Protocolo duro (X-Sync-Version)
SYNC_SUPPORTED_PROTOCOL_VERSIONS 1 Lista de protocolos aceptados
SYNC_CONTRACT_VERSION 1 Forma de los payloads
SYNC_APP_COMPATIBILITY_POLICY same_version en config none, same_version, minimum_version, explicit_list
SYNC_MINIMUM_APP_VERSION 2.1.6 en .env.example Baseline con minimum_version
SYNC_REQUIRED_APP_VERSION APP_VERSION Solo con same_version

En producción se recomienda minimum_version con la baseline explícita: el default del config es same_version y bloquearía a cualquier build distinto. Tras cambiar .env, limpia o regenera la caché de configuración:

php artisan config:clear
# o en producción:
php artisan config:cache

Verificación con un token del negocio:

curl -s https://mi-servidor.example/api/v1/sync/bootstrap \
  -H "Authorization: Bearer <token>" \
  -H "X-Sync-Version: 1" \
  -H "X-Client-App-Version: 2.1.6"

La respuesta debe traer sync_version, contract_version, compatibility.policy, media_policy: "device_local" y supported_entities sin duplicados.

Licencias

Las licencias viven en el backend. Ajusta LICENSING_DEFAULT_ACTIVATIONS_LIMIT (3 por defecto), LICENSING_OFFLINE_GRACE_DAYS (7) y deja LICENSING_ENFORCE_SYNC_GATE=false hasta que la flota esté actualizada. Para importar el histórico de Digital License Manager:

php artisan licensing:import-dlm /ruta/export.json --dry-run
php artisan licensing:import-dlm /ruta/export.json --business-map=negocios.csv

Si quedan apps viejas que llaman a /wp-json/dlm/, aplica el bloque de deploy/nginx/wp-json-dlm.conf en el vhost de WordPress y recarga:

nginx -t && systemctl reload nginx

Correo y HTTPS

MAIL_MAILER=log es el valor de .env.example: los correos de verificación y recuperación no salen sin configurar un transporte real. El único ejemplo de servidor web del repositorio es el proxy del shim de licencias; no hay un vhost completo del backend, que en el entorno de referencia lo sirve Laravel Cloud.

Pendiente de validación

FILESYSTEM_DISK=local y media_policy: device_local indican que las fotos de producto son locales por dispositivo: el backend las descarta. El repositorio no documenta enlaces simbólicos públicos ni un php artisan storage:link, así que no lo incluyas como paso obligatorio hasta confirmarlo.

Pendiente de validación

No hay en el repositorio un procedimiento de respaldo previo a actualizar ni una guía de correo en producción. Confirma con el Lead el transporte SMTP y el procedimiento de backup/restauración de la base antes de tocar un cliente.

Verificación tras el despliegue

  1. GET /up responde correctamente (la ruta de health está registrada en bootstrap/app.php).
  2. El bootstrap de sync devuelve el contrato esperado con un token válido.
  3. Tests y estilo, según el checklist del repo:
vendor/bin/pint --dirty --format agent
php artisan test --compact

Siguiente paso

↑↓ para navegar · Enter para abrir · Esc para cerrar