Instalación de InvoiceShelf: Guía de Configuración Paso a Paso

InvoiceShelf es una solución robusta de gestión de facturación y gastos diseñada para quienes buscan autonomía sobre sus datos financieros. Al ser una plataforma self-hosted, permite eliminar costes por usuario y garantizar la privacidad de la información sensible en tu propia infraestructura.

Antes de comenzar, puedes consultar la ficha técnica completa en InvoiceShelf en HostingByte para conocer sus capacidades de facturación recurrente y soporte multi-moneda.

1. Requisitos Previos

Dependiendo del método de instalación elegido, los requisitos técnicos varían:

Para Docker (Recomendado): Un servidor con Docker y Docker Compose instalados. Este método es el preferido para entornos de producción ya que aísla las dependencias del sistema operativo y facilita las actualizaciones.
Para Instalación Manual: Servidor con PHP 8.2+, soporte para extensiones estándar de Laravel (bcmath, curl, gd, mbstring, xml), una base de datos MySQL o PostgreSQL, y un servidor web (Nginx o Apache).
Conectividad: Acceso a internet para descargar las imágenes de Docker o los paquetes necesarios durante el proceso de instalación manual.

2. Opción A: Instalación mediante Docker (Recomendada)

Esta es la vía más rápida y segura, ya que utiliza contenedores para gestionar automáticamente las dependencias del entorno.

Obtener la imagen oficial: Utiliza la imagen oficial en Docker Hub. La versión estable actual es invoiceshelf/invoiceshelf:2.4.6 (o la etiqueta latest).
Configurar el archivo de entorno: Crea un archivo .env basado en el ejemplo proporcionado por el proyecto para configurar las variables críticas como la base de datos, claves de correo y credenciales de Stripe.
Levantar los contenedores: Ejecuta el comando en tu terminal:
```
docker-compose up -d
```
Nota: El flag -d ejecuta los servicios en segundo plano (detached mode).
Verificación: Una vez levantados, accede a la IP de tu servidor o dominio para verificar que el panel de administración esté accesible y los contenedores estén en estado "running".

3. Opción B: Instalación Manual

Ideal si prefieres gestionar directamente los binarios en un entorno web tradicional.

Descargar el paquete: Obtén la última versión estable (ej. 2.4.6) desde el repositorio oficial o descarga el archivo ZIP de la última versión disponible.
Preparar la base de datos: Crea una base de datos y un usuario dedicado para InvoiceShelf en tu servidor MySQL o PostgreSQL.
Ejecutar el asistente (Wizard): Tras descomprimir los archivos en tu directorio web, accede a la URL de tu dominio. El sistema detectará la falta de configuración y lanzará un asistente de instalación guiado.
Este wizard te guiará automáticamente a través de:
- Configuración de las claves de aplicación (APP_KEY).
- Optimización de caché y limpieza de archivos temporales.
- Generación de activos de frontend (Vue.js).
- Migración de la base de datos y carga de datos iniciales.

4. Configuración Post-Instalación

Una vez instalado, es fundamental configurar los servicios críticos para que el sistema sea funcional:

Configurar Correo: Es vital para enviar facturas automáticas y recordatorios de pago. Se recomienda usar un servicio SMTP o una API como Mailgun/Postmark.
Integrar Stripe: Si planeas aceptar pagos con tarjeta, introduce tus claves de API en la sección de configuración de pagos para habilitar el checkout online.
Multi-moneda y Multi-empresa: Define tu moneda base y configura las reglas fiscales si gestionas múltiples unidades de negocio bajo una misma instalación.

Mantenimiento y Seguridad

Backups: En Docker, realiza copias periódicas del volumen donde reside la base de datos (ej. /var/lib/mysql). En instalaciones manuales, utiliza herramientas como mysqldump.
Actualizaciones: En Docker, actualiza las imágenes con docker-compose pull y reinicia los servicios. En manual, sigue el proceso de actualización del core de Laravel.
Seguridad SSL: Es obligatorio contar con un certificado SSL (ej. Let's Encrypt) antes de procesar datos financieros o información de clientes.

Errores Comunes y Soluciones

Problema	Causa Probable	Solución
Error de conexión a DB	Credenciales incorrectas en `.env` o puerto bloqueado por firewall.	Verifica el archivo .env y asegúrate de que el servidor de BD acepte conexiones desde la IP del servidor web.
Fallo en generación de activos	Falta de Node.js o dependencias de NPM (en instalación manual).	Instala Node.js y ejecuta `npm install` seguido de `npm run build` antes de iniciar el wizard.
Problemas con decimales en moneda extranjera	Versión antigua del software o base de datos no compatible.	Asegúrate de estar en la versión 2.4+ y que tu DB sea PostgreSQL si manejas muchas monedas con decimales complejos.

Preguntas Frecuentes (FAQ)

¿Es difícil configurar el portal de clientes?
No, una vez instalada la base, el portal se activa mediante la configuración de los perfiles de usuario en el panel administrativo.

¿Puedo usar InvoiceShelf para múltiples empresas?
Sí, cuenta con funciones de multi-tenancy que permiten gestionar varias unidades bajo una misma instalación, cada una con su propia identidad visual y moneda local.

Fuentes: Repositorio Oficial | Sitio Web Oficial

Cómo instalar y configurar InvoiceShelf: Guía paso a paso