Sin categoría

BookStack: Plataforma de documentación y wiki autohospedada

Publicado por


BookStack
Self-hosted Documentation Platform

BookStack: Plataforma de documentación y wiki autohospedada

Organiza conocimiento con una interfaz tipo libro, construida sobre Laravel y PHP, lista para despliegue con Docker.

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:


GENBYTE Homelab · Docker · Self-Hosting Docker Open Source Self-Host Suscríbete al canal GENBYTE

Clickea la miniatura para ir a YouTube

¿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 interna o pública. Estructurada en estanterías, libros, capítulos y páginas, ofrece una experiencia de lectura y edición similar a una biblioteca digital. El proyecto está desarrollado en PHP con el framework Laravel, utiliza MySQL como base de datos y proporciona una interfaz web responsiva con editor WYSIWYG y soporte Markdown. La gestión del repositorio se ha trasladado a Codeberg, aunque el espejo en GitHub permanece accesible.

Interfaz jerárquica tipo libro, editor visual y Markdown, control de versiones de páginas, búsqueda full-text, permisos granulares y autenticación LDAP/OAuth2.

Características principales

Organización jerárquica

Estructura el contenido en estanterías, libros, capítulos y páginas para una navegación intuitiva.

Editor dual

Permite editar en modo WYSIWYG o Markdown con previsualización en tiempo real, impulsado por CodeMirror 6.

Control de versiones

Cada cambio en una página genera una revisión accesible desde el historial, con comparación de diferencias.

Búsqueda integrada

Indexación full-text nativa para localizar contenido al instante en toda la instancia.

Gestión de usuarios y permisos

Roles personalizables, permisos por entidad y soporte para autenticación externa (LDAP, OAuth2, SAML).

Adjuntos e imágenes

Subida de archivos e imágenes con almacenamiento local o S3-compatible, y inserción directa en el editor.

API REST

Expone endpoints para integración programática, documentados en la propia instancia bajo /api.

Multilingüe

Interfaz traducida a decenas de idiomas y soporte para contenido en múltiples lenguas.

Requisitos del sistema

  • PHP 8.2 o superior (requerido por Laravel 11)
  • MySQL 8.0+ o MariaDB 10.5+
  • Servidor web (Nginx/Apache) con PHP-FPM
  • Composer para dependencias PHP
  • Node.js 20+ y npm para compilar assets frontend
  • Extensiones PHP: bcmath, ctype, fileinfo, gd, iconv, intl, mbstring, openssl, pdo_mysql, tokenizer, xml, zip
  • Mínimo 1 GB RAM recomendado para instancia pequeña

Instalación con Docker Compose

Clonar el repositorio

Obtén el código desde el repositorio oficial en Codeberg o el espejo de GitHub.

git clone https://codeberg.org/bookstack/bookstack.git
cd bookstack

Instalar dependencias PHP

Ejecuta Composer para instalar las librerías del backend.

composer install –no-dev –optimize-autoloader

Instalar y compilar assets frontend

Instala dependencias Node y genera los archivos CSS/JS de producción.

npm ci
npm run production

Configurar variables de entorno

Copia el archivo de ejemplo y ajusta los valores obligatorios: APP_KEY, APP_URL, credenciales de base de datos y correo.

cp .env.example .env
php artisan key:generate
# Edita .env con tu editor preferido

Ejecutar migraciones y seed inicial

Crea las tablas en la base de datos y genera el usuario administrador inicial.

php artisan migrate –force
php artisan db:seed –force

Configurar permisos de almacenamiento

Asegura que el usuario del servidor web pueda escribir en storage, bootstrap/cache y public/uploads.

chown -R www-data:www-data storage bootstrap/cache public/uploads
chmod -R 775 storage bootstrap/cache public/uploads

Configurar servidor web (ejemplo Nginx)

Apunta el root a la carpeta public/ y configura PHP-FPM. Habilita HTTPS en producción.

server {
listen 80;
server_name docs.ejemplo.com;
root /var/www/bookstack/public;
index index.php;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
include fastcgi_params;
}
}

Acceder al proyecto

Interfaz web

Accede a la URL configurada en APP_URL (p. ej. https://docs.ejemplo.com). El primer usuario registrado se convierte en administrador automáticamente.

Línea de comandos (CLI)

Utiliza `php artisan` desde la raíz del proyecto para tareas de mantenimiento: migraciones, limpieza de caché, regeneración de URLs, envío de emails de prueba, etc.

API REST

Disponible en `/api` con autenticación mediante token personal (Settings > API Tokens). Documentación interactiva en `/api/documentation`.

Casos de uso

  • Wiki interna para equipos de desarrollo y operaciones
  • Base de conocimiento de producto o servicio (knowledge base)
  • Documentación técnica de APIs, arquitectura y runbooks
  • Manuales de usuario y guías de onboarding
  • Repositorio de procedimientos operativos estándar (SOPs)
  • Portafolio de proyectos con estructura de libros y capítulos

Configuración avanzada

Almacenamiento de archivos en S3

Configura STORAGE_TYPE=s3 y define las variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET y AWS_URL en .env para servir adjuntos desde almacenamiento objeto.

STORAGE_TYPE=s3
AWS_ACCESS_KEY_ID=tu_access_key
AWS_SECRET_ACCESS_KEY=tu_secret_key
AWS_DEFAULT_REGION=eu-west-1
AWS_BUCKET=bookstack-uploads
AWS_URL=https://bookstack-uploads.s3.eu-west-1.amazonaws.com

Autenticación LDAP / Active Directory

Habilita LDAP estableciendo AUTH_METHOD=ldap y configurando los parámetros LDAP_* en .env (host, puerto, base_dn, user_filter, bind credentials). Requiere extensión PHP ldap.

AUTH_METHOD=ldap
LDAP_SERVER=ldap.ejemplo.com
LDAP_PORT=389
LDAP_BASE_DN=ou=users,dc=ejemplo,dc=com
LDAP_USER_FILTER=(&(objectClass=user)(sAMAccountName={username}))
LDAP_BIND_DN=cn=bookstack,ou=service,dc=ejemplo,dc=com
LDAP_BIND_PASSWORD=secreto

OAuth2 / OpenID Connect (GitHub, GitLab, Google, Azure AD, Keycloak)

Configura AUTH_METHOD=oauth2 y define OAUTH2_* variables: client_id, client_secret, authorization_endpoint, token_endpoint, user_endpoint, scopes y claim_mapping.

AUTH_METHOD=oauth2
OAUTH2_CLIENT_ID=tu_client_id
OAUTH2_CLIENT_SECRET=tu_client_secret
OAUTH2_AUTHORIZATION_ENDPOINT=https://gitlab.com/oauth/authorize
OAUTH2_TOKEN_ENDPOINT=https://gitlab.com/oauth/token
OAUTH2_USER_ENDPOINT=https://gitlab.com/api/v4/user
OAUTH2_SCOPES=read_user
OAUTH2_USERNAME_CLAIM=username
OAUTH2_EMAIL_CLAIM=email
OAUTH2_DISPLAY_NAME_CLAIM=name

Actualización de URLs tras cambio de dominio

Si modificas APP_URL, ejecuta el comando de actualización para reescribir enlaces almacenados en la base de datos.

php artisan bookstack:update-url https://antiguo.ejemplo.com https://nuevo.ejemplo.com

Tareas programadas (cron)

Añade la entrada al crontab del usuario que ejecuta la aplicación para que el programador de Laravel procese colas, limpieza y notificaciones.

* * * * * cd /var/www/bookstack && php artisan schedule:run >> /dev/null 2>&1

Colas de trabajo (queue worker)

Para envío de emails y tareas en segundo plano, ejecuta un worker persistente (systemd, supervisord o docker).

php artisan queue:work –sleep=3 –tries=3 –timeout=60

Gestión y mantenimiento

Actualizar BookStack

Descarga la última versión, actualiza dependencias, migra la base de datos y limpia cachés.

git pull origin release
composer install –no-dev –optimize-autoloader
npm ci && npm run production
php artisan migrate –force
php artisan cache:clear
php artisan view:clear
php artisan config:clear

Backup de base de datos y archivos

Realiza dump de MySQL y copia de la carpeta storage/uploads (si usas almacenamiento local).

mysqldump -u bookstack -p bookstack > backup_$(date +%F).sql
tar -czf uploads_$(date +%F).tar.gz storage/uploads

Restaurar backup

Importa el dump SQL y descomprime los adjuntos en storage/uploads.

mysql -u bookstack -p bookstack < backup_2024-01-15.sql
tar -xzf uploads_2024-01-15.tar.gz -C /var/www/bookstack

Limpiar cachés y recompilación

Útil tras cambios de configuración o actualizaciones de assets.

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear
npm run production

Comprobar salud del sistema

Ejecuta el comando de diagnóstico integrado para detectar problemas de configuración, permisos o conectividad.

php artisan bookstack:health-check

Stack técnico

  • PHP 8.2+
  • Laravel 11
  • MySQL 8 / MariaDB 10.5+
  • Node.js 20+
  • Sass (CSS)
  • esbuild (JS bundling)
  • CodeMirror 6 (editor)
  • Markdown-it (renderizado Markdown)
  • Snabbdom (virtual DOM)
  • SortableJS (drag & drop)
  • Docker (desarrollo)
  • Nginx / Apache + PHP-FPM (producción)

Referencias oficiales

Apoya el canal GENBYTE

¿Te ha sido útil este contenido?

Suscríbete a YouTube
Newsletter GENBYTE
Ko-fi
Contacto: [email protected]

Sígueme en mis redes sociales

YouTube
Telegram
Discord
GitHub
Blog
Twitter/X

Dejar un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *