Vídeo tutorial en YouTube

Mira el vídeo completo sobre cómo instalar y usar BookStack: Plataforma de documentación y wiki autohospedada en el canal GENBYTE:

¿Qué es BookStack: Plataforma de documentación y wiki autohospedada?

BookStack es una aplicación open source diseñada para crear, organizar y compartir documentación técnica, wikis internas y bases de conocimiento. El proyecto estructura la información en estanterías, libros, capítulos y páginas, ofreciendo una experiencia de navegación similar a una biblioteca digital. Está desarrollado en PHP utilizando el framework Laravel y su interfaz frontend emplea tecnologías modernas como CodeMirror 6 para edición, Sass para estilos y TypeScript para lógica de cliente. El repositorio original en GitHub indica que la gestión principal se ha trasladado a Codeberg, manteniendo la licencia MIT y una comunidad activa con más de 19.000 estrellas.

Características principales

Requisitos del sistema

• Docker y Docker Compose (para despliegue contenedorizado)
• MySQL 8.4 o MariaDB compatible (base de datos relacional)
• PHP 8.2+ con extensiones requeridas por Laravel (PDO, OpenSSL, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath, Fileinfo, GD o Imagick)
• Node.js 22+ y npm (para compilación de assets frontend en desarrollo)
• Servidor web compatible (Nginx/Apache) para producción con PHP-FPM
• Mínimo 1 GB RAM y 2 vCPU recomendados para instancias pequeñas

Instalación con Docker Compose

Clonar repositorio y preparar entorno

Clona el repositorio oficial y copia el archivo de ejemplo de variables de entorno. Ajusta los valores según tu entorno (APP_URL, credenciales de base de datos, configuración de correo, etc.).

Despliegue en desarrollo con Docker Compose

El repositorio incluye un docker-compose.yml orientado a desarrollo. Levanta los servicios (base de datos MySQL, aplicación, Node para assets y Mailhog para pruebas de correo). La variable DEV_PORT define el puerto expuesto (por defecto 8080).

Generar clave de aplicación y migraciones

Dentro del contenedor de la aplicación, genera la clave de cifrado y ejecuta las migraciones de base de datos. En el entorno Docker de desarrollo, el entrypoint ya ejecuta estos pasos, pero en producción deben ejecutarse manualmente.

Compilar assets frontend (producción)

Para entornos de producción, compila los assets CSS y JavaScript optimizados. En desarrollo, el servicio Node con entrypoint.node.sh maneja la compilación en modo watch.

Acceder al proyecto

Aplicación web

Accede a BookStack en http://localhost:8080 (puerto configurable con DEV_PORT). En producción, usa el dominio configurado en APP_URL.

Interfaz de correo (Mailhog)

En el entorno de desarrollo, Mailhog expone su UI en http://localhost:8025 (puerto configurable con DEV_MAIL_PORT) para inspeccionar correos de prueba.

Credenciales iniciales

El primer usuario registrado se convierte en administrador automáticamente. No hay credenciales por defecto predefinidas.

Casos de uso

• Documentación técnica de proyectos software con versionado y búsqueda
• Wiki interna para equipos de ingeniería, soporte o recursos humanos
• Base de conocimiento pública o privada para clientes y partners
• Manuales de procesos y procedimientos operativos estandarizados
• Portafolio de documentación de APIs con ejemplos de código y Markdown
• Gestión de notas de reunión, decisiones y arquitectura (ADR)

Configuración avanzada

Configuración de almacenamiento

Por defecto usa almacenamiento local (STORAGE_TYPE=local). Para S3-compatible, configura STORAGE_TYPE=s3 y variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET, AWS_URL. Consulta la documentación oficial para opciones de visibilidad y CDN.

Configuración de correo SMTP

Define MAIL_DRIVER=smtp y completa MAIL_HOST, MAIL_PORT, MAIL_USERNAME, MAIL_PASSWORD, MAIL_ENCRYPTION (tls/ssl/null). Prueba la configuración desde la interfaz en Ajustes > Mantenimiento > Enviar correo de prueba.

Actualización de URL de la aplicación

Si cambias APP_URL, ejecuta el comando artisan para actualizar URLs almacenadas en base de datos (enlaces internos, imágenes, etc.). Reemplaza las URLs antigua y nueva según corresponda.

Autenticación externa (LDAP/OIDC/SAML)

BookStack soporta proveedores externos mediante paquetes Laravel Socialite y configuración adicional. Requiere definir variables de entorno específicas y, en algunos casos, instalar paquetes composer adicionales. Consulta la documentación de administración para pasos detallados.

Tareas programadas y colas

Configura el programador de Laravel (cron) para ejecutar `php artisan schedule:run` cada minuto. Para colas, usa `php artisan queue:work –sleep=3 –tries=3` con un gestor de procesos como Supervisor. En Docker, puedes añadir servicios dedicados para scheduler y worker.

Gestión y mantenimiento

Actualización de versión

Actualiza el código (git pull o nueva imagen Docker), ejecuta migraciones y limpia cachés. En Docker, reconstruye la imagen si hay cambios en dependencias o Dockerfile.

Copia de seguridad

Realiza copias de la base de datos (mysqldump) y del directorio de almacenamiento (storage/ y public/uploads/ si usas local). Automatiza con scripts cron y almacena en ubicación remota.

Limpieza de cachés y optimización

Ejecuta comandos de optimización de Laravel periódicamente o tras cambios de configuración. Incluye caché de rutas, configuración, vistas y autoloader de Composer.

Monitoreo de salud

Expone endpoint de health check en /health (requiere configuración de ruta). Verifica conectividad a base de datos, espacio en disco, cola de trabajos y latencia de respuesta. Integra con Prometheus/Grafana o Uptime Kuma.

Stack técnico

• PHP 8.2+
• Laravel 11.x
• MySQL 8.4 / MariaDB 10.6+
• Node.js 22 LTS
• NPM / Sass / esbuild / TypeScript
• CodeMirror 6 (editor)
• Markdown-it (renderizado Markdown)
• Snabbdom (virtual DOM)
• SortableJS (arrastrar y soltar)
• Docker / Docker Compose
• Nginx / Apache + PHP-FPM (producción)

Apoya el canal GENBYTE

Sígueme en mis redes sociales