diff --git a/Actualización.md b/Actualización.md new file mode 100644 index 0000000..7000d81 --- /dev/null +++ b/Actualización.md @@ -0,0 +1,245 @@ +# Actualización + +Mantén BookStack y MariaDB actualizados de forma segura. + +## Pre-requisitos + +⚠️ **SIEMPRE haz backup antes de actualizar** + +```bash +# Backup rápido +docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack > bookstack-pre-update-$(date +%Y%m%d).sql +docker run --rm -v bookstack_config:/backup -v $(pwd):/target alpine tar czf /target/bookstack-config-pre-update.tar.gz -C /backup . +``` + +--- + +## Actualizar BookStack + +### Proceso Manual + +```bash +# 1. Backup (ver arriba) + +# 2. Detener stack +docker stop bookstack bookstack-db + +# 3. Actualizar imágenes +docker pull lscr.io/linuxserver/bookstack:latest +docker pull mariadb:11-alpine + +# 4. Iniciar MariaDB primero +docker start bookstack-db +sleep 10 + +# 5. Iniciar BookStack +docker start bookstack + +# 6. Verificar logs +docker logs -f bookstack + +# 7. Acceder y verificar +# https://bookstack.tudominio.com +# Settings → About → Verificar versión +``` + +### Con Portainer + +1. Ve al stack `bookstack` +2. Click en **Pull and redeploy** +3. Espera 1-2 minutos +4. Verifica logs y acceso + +--- + +## Actualizar MariaDB + +### Actualización Menor (11.x → 11.y) + +```bash +# Actualizar normalmente +docker stop bookstack bookstack-db +docker pull mariadb:11-alpine +docker start bookstack-db +sleep 15 +docker start bookstack +``` + +### Actualización Mayor (10 → 11) + +⚠️ **Requiere dump y restore** + +```bash +# 1. Backup completo +docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack > bookstack-mariadb-upgrade.sql + +# 2. Detener todo +docker stop bookstack bookstack-db + +# 3. Eliminar contenedor y volumen antiguo +docker rm bookstack-db +docker volume rm bookstack_db + +# 4. Recrear volumen +docker volume create bookstack_db + +# 5. Iniciar MariaDB 11 +docker compose up -d bookstack-db + +# 6. Esperar inicialización +sleep 20 + +# 7. Restaurar datos +cat bookstack-mariadb-upgrade.sql | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack + +# 8. Iniciar BookStack +docker start bookstack + +# 9. Verificar +docker logs bookstack +``` + +--- + +## Rollback (Revertir Actualización) + +### Rollback Rápido + +```bash +# 1. Detener todo +docker stop bookstack bookstack-db + +# 2. Volver a versión anterior de imagen +docker pull lscr.io/linuxserver/bookstack:v24.05.4 +docker tag lscr.io/linuxserver/bookstack:v24.05.4 lscr.io/linuxserver/bookstack:latest + +# 3. Restaurar BD desde backup +gunzip < bookstack-pre-update-20250101.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack + +# 4. Iniciar +docker start bookstack-db +sleep 10 +docker start bookstack +``` + +### Rollback Completo + +```bash +# 1. Detener y eliminar todo +docker stop bookstack bookstack-db +docker rm bookstack bookstack-db +docker volume rm bookstack_config bookstack_db + +# 2. Recrear volúmenes +docker volume create bookstack_config +docker volume create bookstack_db + +# 3. Iniciar stack +docker compose up -d bookstack-db +sleep 20 + +# 4. Restaurar desde backups +gunzip < bookstack-pre-update.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack +docker run --rm -v bookstack_config:/restore -v $(pwd):/source alpine tar xzf /source/bookstack-config-pre-update.tar.gz -C /restore + +# 5. Iniciar BookStack +docker start bookstack +``` + +--- + +## Actualización Automática con Watchtower + +### Desplegar Watchtower + +```yaml +services: + watchtower: + image: containrrr/watchtower + restart: unless-stopped + environment: + WATCHTOWER_CLEANUP: "true" + WATCHTOWER_INCLUDE_STOPPED: "false" + WATCHTOWER_SCHEDULE: "0 0 4 * * *" # 4 AM diario + WATCHTOWER_ROLLING_RESTART: "true" + volumes: + - /var/run/docker.sock:/var/run/docker.sock + labels: + - "com.centurylinklabs.watchtower.enable=true" +``` + +### Excluir BookStack de Watchtower + +Si quieres control manual, añade label a `bookstack`: + +```yaml +services: + bookstack: + labels: + - "com.centurylinklabs.watchtower.enable=false" +``` + +--- + +## Checklist Post-Actualización + +### Verificar Funcionalidad + +- [ ] BookStack accesible en https://bookstack.tudominio.com +- [ ] Login funciona correctamente +- [ ] Libros/capítulos/páginas visibles +- [ ] Búsqueda funciona +- [ ] Imágenes cargan correctamente +- [ ] Editor funciona (crear/editar páginas) +- [ ] API responde (si la usas) +- [ ] LDAP/SAML funciona (si lo usas) + +### Verificar Logs + +```bash +# Sin errores críticos +docker logs bookstack | grep -i error +docker logs bookstack | grep -i fatal + +# BD conectada +docker logs bookstack | grep "Database" +``` + +### Verificar Versión + +**Settings → About**: +- **BookStack Version**: Debe ser la nueva versión +- **PHP Version**: Verificar compatibilidad + +--- + +## Mantenimiento + +### Limpiar Imágenes Antiguas + +```bash +# Listar imágenes antiguas +docker images | grep bookstack +docker images | grep mariadb + +# Eliminar imágenes sin usar +docker image prune -a +``` + +### Optimizar Base de Datos + +```bash +# Optimizar tablas +docker exec bookstack-db mariadb-optimize -u bookstack -p${DB_PASSWORD} bookstack + +# Reparar tablas (si hay corrupción) +docker exec bookstack-db mariadb-check -u bookstack -p${DB_PASSWORD} --auto-repair bookstack +``` + +--- + +## Próximos Pasos + +1. **[Backup](Backup-y-Restauración)** - Automatiza backups regulares +2. **Monitoriza** - Configura alertas de caídas +3. **Documenta** - Mantén registro de versiones diff --git a/Backup-y-Restauración.md b/Backup-y-Restauración.md new file mode 100644 index 0000000..4e5fda2 --- /dev/null +++ b/Backup-y-Restauración.md @@ -0,0 +1,189 @@ +# Backup y Restauración + +Protege tus datos de BookStack con backups automáticos. + +## Qué Hacer Backup + +BookStack tiene 2 componentes críticos: + +1. **MariaDB** - Base de datos (lo más importante) +2. **Configuración** - `/config/` (uploads, imágenes, configuración) + +--- + +## Backup Manual + +### MariaDB (Crítico) + +```bash +# Backup completo +docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack > bookstack-backup-$(date +%Y%m%d).sql + +# Backup comprimido (ahorra espacio) +docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack | gzip > bookstack-backup-$(date +%Y%m%d).sql.gz + +# Verificar backup +gunzip -c bookstack-backup-20250101.sql.gz | head -20 +``` + +### Configuración y Uploads + +```bash +# Backup del volumen de configuración +docker run --rm -v bookstack_config:/backup -v $(pwd):/target alpine tar czf /target/bookstack-config-$(date +%Y%m%d).tar.gz -C /backup . + +# Verificar +tar tzf bookstack-config-20250101.tar.gz | head +``` + +--- + +## Backup Automático + +### Script de Backup + +Crea `/root/backup-bookstack.sh`: + +```bash +#!/bin/bash + +# Configuración +BACKUP_DIR="/backups/bookstack" +DATE=$(date +%Y%m%d-%H%M%S) +RETENTION_DAYS=7 +DB_PASSWORD="tu_password_aqui" + +# Crear directorio +mkdir -p $BACKUP_DIR + +# MariaDB (comprimido) +echo "Backing up MariaDB..." +docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack | gzip > $BACKUP_DIR/bookstack-db-$DATE.sql.gz + +# Configuración +echo "Backing up configuration..." +docker run --rm -v bookstack_config:/backup -v $BACKUP_DIR:/target alpine tar czf /target/bookstack-config-$DATE.tar.gz -C /backup . + +# Limpiar backups antiguos +echo "Cleaning old backups..." +find $BACKUP_DIR -name "*.sql.gz" -mtime +$RETENTION_DAYS -delete +find $BACKUP_DIR -name "*.tar.gz" -mtime +$RETENTION_DAYS -delete + +# Verificar +DB_SIZE=$(stat -f%z "$BACKUP_DIR/bookstack-db-$DATE.sql.gz" 2>/dev/null || stat -c%s "$BACKUP_DIR/bookstack-db-$DATE.sql.gz") +echo "Backup completado: $DATE (BD: $(($DB_SIZE / 1024 / 1024))MB)" +``` + +### Automatizar con Cron + +```bash +chmod +x /root/backup-bookstack.sh +crontab -e + +# Backup diario a las 3 AM +0 3 * * * /root/backup-bookstack.sh >> /var/log/backup-bookstack.log 2>&1 +``` + +--- + +## Restauración + +### Restaurar desde Backup + +```bash +# 1. Detener BookStack +docker stop bookstack + +# 2. Restaurar MariaDB +gunzip < bookstack-db-20250101.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack + +# 3. Restaurar configuración +docker run --rm -v bookstack_config:/restore -v $(pwd):/source alpine tar xzf /source/bookstack-config-20250101.tar.gz -C /restore + +# 4. Limpiar caché +docker exec bookstack php artisan cache:clear + +# 5. Iniciar BookStack +docker start bookstack +``` + +### Migración a Otro Servidor + +```bash +# Servidor origen +docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack | gzip > bookstack-migration.sql.gz +docker run --rm -v bookstack_config:/backup -v $(pwd):/target alpine tar czf /target/bookstack-config-migration.tar.gz -C /backup . + +# Copiar a servidor destino +scp bookstack-*.gz usuario@servidor-destino:/tmp/ + +# Servidor destino +cd /tmp +gunzip < bookstack-migration.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack +docker run --rm -v bookstack_config:/restore -v /tmp:/source alpine tar xzf /source/bookstack-config-migration.tar.gz -C /restore +docker restart bookstack +``` + +--- + +## Backup Remoto + +### Sincronizar con S3/MinIO + +```bash +#!/bin/bash +BACKUP_DIR="/backups/bookstack" +S3_BUCKET="s3://mi-bucket/bookstack/" + +# Hacer backup local primero +/root/backup-bookstack.sh + +# Sincronizar con S3 +aws s3 sync $BACKUP_DIR $S3_BUCKET --storage-class GLACIER + +# O con rclone +rclone sync $BACKUP_DIR minio:bookstack-backups +``` + +### Sincronizar con Rsync + +```bash +#!/bin/bash +BACKUP_DIR="/backups/bookstack" +REMOTE_SERVER="backup@servidor-remoto" +REMOTE_PATH="/backups/bookstack" + +# Sincronizar +rsync -avz --delete $BACKUP_DIR/ $REMOTE_SERVER:$REMOTE_PATH/ +``` + +--- + +## Verificación de Backups + +### Script de Verificación + +```bash +#!/bin/bash +BACKUP_FILE="/backups/bookstack/bookstack-db-latest.sql.gz" + +# Verificar integridad +if gunzip -t "$BACKUP_FILE" 2>/dev/null; then + echo "✓ Backup válido" + + # Verificar contenido + TABLES=$(gunzip -c "$BACKUP_FILE" | grep "CREATE TABLE" | wc -l) + echo "✓ Contiene $TABLES tablas" +else + echo "✗ Backup corrupto" + exit 1 +fi +``` + +--- + +## Próximos Pasos + +1. **[Actualización](Actualización)** - Mantén BookStack actualizado +2. **Automatiza** - Configura cron para backups automáticos +3. **Prueba restauración** - Verifica que los backups funcionan diff --git a/Configuración-Inicial.md b/Configuración-Inicial.md new file mode 100644 index 0000000..45a90cc --- /dev/null +++ b/Configuración-Inicial.md @@ -0,0 +1,206 @@ +# Configuración Inicial + +Pasos para configurar BookStack tras el primer despliegue. + +## Primer Acceso + +1. Accede a BookStack mediante tu dominio configurado +2. Login con credenciales por defecto: + - **Email**: `admin@admin.com` + - **Password**: `password` + +> ⚠️ **CRÍTICO**: Estas son credenciales públicas. **Cámbialas INMEDIATAMENTE**. + +### Cambiar Contraseña de Admin + +1. Click en tu avatar (esquina superior derecha) +2. **Edit Profile** +3. **Change Password** +4. Ingresa contraseña nueva (mínimo 8 caracteres) +5. **Save** + +--- + +## Configuración Básica + +### Settings → Settings + +Accede al panel de administración: **Settings** (engranaje superior derecho) + +#### Información de la Aplicación + +- **Application Name**: `Mi Wiki Corporativa` +- **Application Logo**: Sube tu logo (PNG/SVG recomendado) +- **Application Icon**: Favicon para navegador +- **Default Language**: `Español` (o tu idioma preferido) + +#### Registro y Acceso + +**Settings → Registration Settings**: + +- **Allow public registration**: ❌ Desactivar +- **Allow public viewing**: ✅ Activar si quieres permitir lectura sin login +- **Default role for new users**: `Viewer` (solo lectura) +- **Email confirmation required**: ✅ Activar (si tienes SMTP configurado) + +--- + +## Roles y Permisos + +**Settings → Roles** + +### Roles Por Defecto + +BookStack incluye 3 roles: + +1. **Admin**: Control total del sistema +2. **Editor**: Puede crear y editar todo el contenido +3. **Viewer**: Solo lectura + +### Crear Rol Personalizado + +1. **Settings** → **Roles** → **Create New Role** +2. **Role Name**: `Documentador` (ejemplo) +3. **Role Description**: Descripción del rol + +#### Permisos del Sistema + +- **User management**: Gestión de usuarios +- **Manage system settings**: Acceso a configuración +- **Manage users, roles & permissions**: Gestión de roles +- **Access system API**: Acceso a API REST + +#### Permisos de Contenido + +Para cada tipo (Books, Chapters, Pages): + +- **Create**: Crear nuevo contenido +- **Edit Own**: Editar su propio contenido +- **Edit All**: Editar contenido de otros +- **Delete Own**: Eliminar su propio contenido +- **Delete All**: Eliminar contenido de otros + +4. **Save Role** + +--- + +## Crear Usuarios + +**Settings → Users → Create New User** + +1. **Name**: Nombre completo +2. **Email**: email@example.com +3. **Password**: Contraseña temporal (el usuario debe cambiarla) +4. **Roles**: Seleccionar rol(es) +5. **Send invite email**: ✅ Si tienes SMTP configurado +6. **Save** + +--- + +## Organizar Contenido + +### Crear tu Primer Libro + +1. Click en **Books** (menú superior) +2. **Create New Book** +3. **Name**: `Manual de Usuario` +4. **Description**: Descripción breve +5. **Cover Image**: Imagen de portada (opcional) +6. **Tags**: Etiquetas para organización +7. **Save Book** + +### Crear Capítulos + +1. Dentro del libro, click **New Chapter** +2. **Name**: `Introducción` +3. **Description**: Resumen del capítulo +4. **Save Chapter** + +### Crear Páginas + +1. Dentro del capítulo (o libro), click **New Page** +2. **Name**: `Primeros Pasos` +3. Selecciona editor: + - **WYSIWYG**: Editor visual (como Word) + - **Markdown**: Sintaxis Markdown +4. Escribe contenido +5. **Save Page** + +--- + +## Permisos Granulares + +### Permisos por Libro + +1. Abre el libro +2. Click en **⋮** → **Permissions** +3. **Enable Custom Permissions**: ✅ Activar +4. Selecciona roles y sus permisos: + - **View**: Ver contenido + - **Edit**: Editar contenido + - **Delete**: Eliminar contenido +5. **Save Permissions** + +### Permisos por Capítulo/Página + +Mismo proceso que libros. Los permisos de nivel superior se heredan, pero pueden sobreescribirse. + +--- + +## Personalización Visual + +### Settings → Customization + +#### Esquema de Color + +- **Color Scheme**: `Light` / `Dark` +- **Primary Color**: Color principal de la interfaz (hex: `#0288D1`) + +#### HTML Head Personalizado + +Añade CSS personalizado: + +```html + +``` + +--- + +## Configurar SMTP (Email) + +**Settings → Settings → Email**: + +```env +# Añadir al .env del contenedor +MAIL_DRIVER=smtp +MAIL_HOST=smtp.gmail.com +MAIL_PORT=587 +MAIL_FROM=bookstack@example.com +MAIL_FROM_NAME="BookStack Wiki" +MAIL_USERNAME=tu@email.com +MAIL_PASSWORD=tu_password_app +MAIL_ENCRYPTION=tls +``` + +Reinicia el contenedor: +```bash +docker restart bookstack +``` + +Prueba el email: +**Settings → Maintenance → Send a Test Email** + +--- + +## Próximos Pasos + +1. **[Personalización](Personalización)** - LDAP, temas avanzados +2. **[Backup](Backup-y-Restauración)** - Automatiza backups +3. **Crea contenido** - Empieza a documentar diff --git a/Home.md b/Home.md index 0ab951d..91ed166 100644 --- a/Home.md +++ b/Home.md @@ -1 +1,149 @@ -¡Bienvenidos a la Wiki! \ No newline at end of file +# BookStack Wiki + +Documentación completa para el despliegue y gestión de BookStack con Docker. + +## 📑 Índice + +### Inicio Rápido +- **[Home](Home)** - Esta página +- **[Generar Contraseña](#generar-contraseña)** - Antes de desplegar + +### Modos de Despliegue +- **[Traefik](Traefik)** - Proxy inverso con SSL automático +- **[NPM](NPM)** - Nginx Proxy Manager + +### Configuración y Uso +- **[Configuración Inicial](Configuración-Inicial)** - Primer acceso y setup +- **[Personalización](Personalización)** - LDAP, temas, configuración avanzada +- **[Backup y Restauración](Backup-y-Restauración)** - Protege tus datos +- **[Actualización](Actualización)** - Mantén BookStack actualizado +- **[Solución de Problemas](Solución-de-Problemas)** - Diagnóstico y fixes + +--- + +## ¿Qué es BookStack? + +BookStack es una **plataforma de documentación y wiki** de código abierto que organiza el contenido en una estructura jerárquica intuitiva: Libros → Capítulos → Páginas. + +### Características Principales + +- 📚 **Organización Jerárquica**: Libros, capítulos y páginas +- ✏️ **Editor Dual**: WYSIWYG y Markdown +- 🔍 **Búsqueda Potente**: Indexación completa del contenido +- 🔐 **Control de Acceso**: Permisos granulares por rol +- 📝 **Historial de Cambios**: Seguimiento completo de ediciones +- 🖼️ **Gestión de Imágenes**: Biblioteca de medios integrada +- 🔗 **Integración**: LDAP, SAML 2.0, OAuth (Google, GitHub, etc.) +- 🌍 **Multi-idioma**: Soporte para múltiples idiomas incluido español + +### Casos de Uso + +- **Documentación técnica**: Manuales, guías, procedimientos +- **Base de conocimiento**: Wiki corporativa, FAQ +- **Documentación de proyectos**: Desarrollo de software +- **Políticas y procedimientos**: Compliance, ISO, GDPR +- **Notas colaborativas**: Equipos distribuidos + +--- + +## Inicio Rápido + +### Requisitos + +- Docker Engine +- Portainer (recomendado) +- Red `proxy` creada +- MariaDB 11 (incluido en el compose) + +### Generar Contraseña + +**ANTES de desplegar**, genera 1 contraseña segura: + +```bash +# DB_PASSWORD (MariaDB) +openssl rand -base64 32 +``` + +> ⚠️ **Importante**: Si la contraseña contiene caracteres especiales (`$`, `!`, etc.), usa comillas simples en el `.env`: +> ```env +> DB_PASSWORD='tu_password_con_$_especiales' +> ``` + +### Despliegue Básico + +1. **Crea el stack en Portainer** con Git Repository: + - URL: `https://git.ictiberia.com/groales/bookstack` + - Compose path: `docker-compose.yml` + +2. **Añade variables de entorno**: + ```env + DB_PASSWORD=password_generado + ``` + +3. **Deploy** y espera 1-2 minutos (BookStack inicializa la BD) + +4. **Accede** y configura según tu proxy inverso: + - **[Traefik](Traefik)**: `https://bookstack.tudominio.com` + - **[NPM](NPM)**: Configura Proxy Host primero + - **Login**: Email `admin@admin.com` + password `password` **¡CÁMBIALO INMEDIATAMENTE!** + +--- + +## Arquitectura + +``` +┌─────────────────────────────────────────────────┐ +│ Traefik / NPM (Proxy) │ +│ HTTPS / SSL │ +└────────────────┬────────────────────────────────┘ + │ + ┌─────────▼──────────┐ + │ BookStack │ Puerto 80 + │ (LinuxServer) │ + └─────────┬──────────┘ + │ + ┌─────▼──────┐ + │ MariaDB │ + │ 11 │ + └────────────┘ + (Base Datos) +``` + +### Componentes + +- **BookStack**: Aplicación PHP Laravel (puerto 80) +- **MariaDB 11**: Base de datos MySQL +- **Proxy**: Traefik o NPM para HTTPS + +### Volúmenes + +- `bookstack_config`: Configuración, uploads, imágenes +- `bookstack_db`: Base de datos MariaDB + +--- + +## Próximos Pasos + +1. **Elige tu modo de despliegue**: + - [Traefik](Traefik) - Recomendado para múltiples servicios + - [NPM](NPM) - Más simple para configurar + +2. **Configura BookStack**: + - [Configuración Inicial](Configuración-Inicial) - Primer acceso + - [Personalización](Personalización) - LDAP, temas, etc. + +3. **Protege tus datos**: + - [Backup y Restauración](Backup-y-Restauración) - Automatiza backups + +4. **Mantén actualizado**: + - [Actualización](Actualización) - BookStack y MariaDB + +--- + +## Recursos Oficiales + +- [Documentación BookStack](https://www.bookstackapp.com/docs/) +- [LinuxServer BookStack](https://docs.linuxserver.io/images/docker-bookstack) +- [BookStack GitHub](https://github.com/BookStackApp/BookStack) +- [Demo BookStack](https://demo.bookstackapp.com/) +- [API Docs](https://demo.bookstackapp.com/api/docs) diff --git a/NPM.md b/NPM.md new file mode 100644 index 0000000..6255c05 --- /dev/null +++ b/NPM.md @@ -0,0 +1,99 @@ +# Despliegue con NPM + +Guía para desplegar BookStack con Nginx Proxy Manager. + +## Requisitos + +- NPM desplegado y accesible +- Red Docker `proxy` creada +- DNS apuntando al servidor + +--- + +## Pasos de Despliegue + +### 1. Desplegar BookStack + +En Portainer, crea el stack **sin archivo override** (solo `docker-compose.yml`): + +**Variables de entorno**: +```env +DB_PASSWORD=password_generado +``` + +> ⚠️ **No añadas** `DOMAIN_HOST` - Solo se usa con Traefik + +### 2. Configurar Proxy Host en NPM + +1. Accede a NPM (ej: `https://npm.tudominio.com`) +2. Ve a **Hosts** → **Proxy Hosts** → **Add Proxy Host** + +#### Pestaña Details + +- **Domain Names**: `bookstack.tudominio.com` +- **Scheme**: `http` +- **Forward Hostname / IP**: `bookstack` +- **Forward Port**: `80` +- ✅ **Cache Assets**: Activado +- ✅ **Block Common Exploits**: Activado +- ✅ **Websockets Support**: Activado + +#### Pestaña SSL + +- **SSL Certificate**: `Request a new SSL Certificate` +- **Email**: tu@email.com +- ✅ **Force SSL**: Activado +- ✅ **HTTP/2 Support**: Activado +- ✅ **HSTS Enabled**: Activado (opcional) + +3. **Save** + +### 3. Verificar + +- Accede a `https://bookstack.tudominio.com` +- Verifica el certificado SSL (candado verde) +- Login con `admin@admin.com` / `password` +- **Cambia la contraseña inmediatamente** + +--- + +## Comparativa Traefik vs NPM + +| Aspecto | Traefik | NPM | +|---------|---------|-----| +| **Configuración** | Labels en compose | UI web | +| **SSL** | Automático | Manual por dominio | +| **Dificultad** | Media | Fácil | +| **Renovación SSL** | Automática | Automática | +| **Multi-dominio** | Excelente | Bueno | +| **Recomendado para** | Múltiples servicios | Pocos servicios | + +--- + +## Troubleshooting + +### Error 502 Bad Gateway + +**Verificar**: +```bash +# BookStack corriendo +docker ps | grep bookstack + +# BookStack en red proxy +docker inspect bookstack | grep -A 5 Networks +``` + +### Certificado SSL falla + +**Soluciones**: +- Verificar DNS apunta correctamente +- Intentar con DNS Challenge si puertos 80/443 bloqueados +- Regenerar certificado en NPM UI + +--- + +## Próximos Pasos + +1. **[Configuración Inicial](Configuración-Inicial)** - Configurar BookStack +2. **[Personalización](Personalización)** - LDAP, temas +3. **[Backup](Backup-y-Restauración)** - Automatiza backups diff --git a/Personalización.md b/Personalización.md new file mode 100644 index 0000000..935967a --- /dev/null +++ b/Personalización.md @@ -0,0 +1,264 @@ +# Personalización + +Configuración avanzada de BookStack: LDAP, temas, plugins y más. + +## Autenticación LDAP + +### Configurar LDAP/Active Directory + +Añade estas variables al `.env`: + +```env +# LDAP Básico +AUTH_METHOD=ldap +LDAP_SERVER=ldap://ldap.example.com:389 +LDAP_BASE_DN=dc=example,dc=com +LDAP_DN=cn=bookstack,ou=Services,dc=example,dc=com +LDAP_PASS=password_ldap +LDAP_USER_FILTER=(&(uid=${user})) +LDAP_VERSION=3 + +# Mapeo de Atributos +LDAP_ID_ATTRIBUTE=uid +LDAP_EMAIL_ATTRIBUTE=mail +LDAP_DISPLAY_NAME_ATTRIBUTE=cn + +# Sincronización de Grupos (opcional) +LDAP_USER_TO_GROUPS=true +LDAP_GROUP_ATTRIBUTE=memberOf +LDAP_REMOVE_FROM_GROUPS=true +``` + +Reinicia: +```bash +docker restart bookstack +``` + +### Active Directory + +```env +AUTH_METHOD=ldap +LDAP_SERVER=ldap://dc.example.com:389 +LDAP_BASE_DN=dc=example,dc=com +LDAP_DN=CN=BookStack,OU=Service Accounts,DC=example,DC=com +LDAP_PASS=password +LDAP_USER_FILTER=(&(sAMAccountName=${user})(objectClass=user)) +LDAP_VERSION=3 +LDAP_ID_ATTRIBUTE=sAMAccountName +LDAP_EMAIL_ATTRIBUTE=mail +LDAP_DISPLAY_NAME_ATTRIBUTE=displayName +``` + +--- + +## SAML 2.0 + +### Configurar SAML con ADFS + +```env +AUTH_METHOD=saml2 +SAML2_NAME=ADFS +SAML2_EMAIL_ATTRIBUTE=email +SAML2_DISPLAY_NAME_ATTRIBUTES=name +SAML2_EXTERNAL_ID_ATTRIBUTE=uid +SAML2_IDP_ENTITYID=https://adfs.example.com/adfs/services/trust +SAML2_IDP_SSO=https://adfs.example.com/adfs/ls/ +SAML2_IDP_SLO=https://adfs.example.com/adfs/ls/ +SAML2_AUTOLOAD_METADATA=true +``` + +--- + +## OAuth (Google, GitHub, GitLab) + +### Google OAuth + +1. Crea aplicación OAuth en [Google Cloud Console](https://console.cloud.google.com/) +2. Añade al `.env`: + +```env +AUTH_METHOD=google +GOOGLE_APP_ID=tu-client-id.apps.googleusercontent.com +GOOGLE_APP_SECRET=tu-client-secret +GOOGLE_SELECT_ACCOUNT=true +``` + +### GitHub OAuth + +```env +AUTH_METHOD=github +GITHUB_APP_ID=tu-client-id +GITHUB_APP_SECRET=tu-client-secret +``` + +### GitLab OAuth + +```env +AUTH_METHOD=gitlab +GITLAB_APP_ID=tu-application-id +GITLAB_APP_SECRET=tu-secret +GITLAB_BASE_URI=https://gitlab.example.com +``` + +--- + +## Temas Personalizados + +### CSS Personalizado + +**Settings → Customization → Custom HTML Head Content**: + +```html + +``` + +### JavaScript Personalizado + +```html + +``` + +--- + +## Comandos Útiles + +### Acceder al Contenedor + +```bash +# Shell +docker exec -it bookstack bash + +# Ver comandos artisan disponibles +docker exec bookstack php artisan list +``` + +### Limpiar Caché + +```bash +# Caché de aplicación +docker exec bookstack php artisan cache:clear + +# Caché de configuración +docker exec bookstack php artisan config:clear + +# Caché de vistas +docker exec bookstack php artisan view:clear + +# Todo a la vez +docker exec bookstack php artisan optimize:clear +``` + +### Regenerar Índice de Búsqueda + +```bash +docker exec bookstack php artisan bookstack:regenerate-search +``` + +### Limpiar Sesiones Antiguas + +```bash +docker exec bookstack php artisan bookstack:cleanup-sessions +``` + +--- + +## API REST + +### Habilitar API + +**Settings → Settings → Enable API** + +### Crear Token de API + +1. **Settings → Users** → Selecciona usuario +2. **API Tokens** → **Create Token** +3. **Token Name**: `Script de Backup` +4. **Expiry Date**: Fecha de expiración (opcional) +5. **Save** y copia el token + +### Ejemplo de Uso + +```bash +# Listar libros +curl -H "Authorization: Token tu_token_aqui" \ + https://bookstack.example.com/api/books + +# Crear página +curl -X POST \ + -H "Authorization: Token tu_token_aqui" \ + -H "Content-Type: application/json" \ + -d '{"book_id": 1, "chapter_id": 1, "name": "Nueva Página", "html": "

Contenido

"}' \ + https://bookstack.example.com/api/pages +``` + +Documentación completa: `https://bookstack.example.com/api/docs` + +--- + +## Integración con Herramientas + +### Ansible + +```yaml +- name: Crear página en BookStack + uri: + url: "https://bookstack.example.com/api/pages" + method: POST + headers: + Authorization: "Token {{ bookstack_token }}" + body_format: json + body: + book_id: 1 + name: "Documentación Ansible" + html: "

Generado por Ansible

" +``` + +### Python + +```python +import requests + +headers = {'Authorization': 'Token tu_token_aqui'} +url = 'https://bookstack.example.com/api/books' + +response = requests.get(url, headers=headers) +books = response.json() + +for book in books['data']: + print(f"{book['id']}: {book['name']}") +``` + +--- + +## Próximos Pasos + +1. **[Backup](Backup-y-Restauración)** - Automatiza backups +2. **[Actualización](Actualización)** - Mantén BookStack actualizado +3. **Explora la API** - `https://bookstack.example.com/api/docs` diff --git a/Solución-de-Problemas.md b/Solución-de-Problemas.md new file mode 100644 index 0000000..48678a7 --- /dev/null +++ b/Solución-de-Problemas.md @@ -0,0 +1,355 @@ +# Solución de Problemas + +Diagnóstico y resolución de problemas comunes en BookStack. + +## Diagnóstico General + +### Ver Logs + +```bash +# Logs de BookStack +docker logs bookstack --tail 100 -f + +# Logs de MariaDB +docker logs bookstack-db --tail 50 + +# Logs del stack completo +docker compose logs -f +``` + +### Verificar Estado + +```bash +# Estado de contenedores +docker ps -a | grep bookstack + +# Uso de recursos +docker stats bookstack bookstack-db --no-stream + +# Redes +docker network inspect bookstack-internal +docker network inspect proxy +``` + +--- + +## Problemas Comunes + +### BookStack No Inicia + +**Síntomas**: Contenedor se reinicia constantemente + +**Diagnóstico**: +```bash +docker logs bookstack | grep -i error +docker logs bookstack | grep -i fatal +``` + +**Causas comunes**: + +1. **MariaDB no está listo** + ```bash + docker logs bookstack-db + docker exec bookstack-db mariadb -u bookstack -p${DB_PASSWORD} -e "SELECT 1" + ``` + **Solución**: Esperar o reiniciar MariaDB + ```bash + docker restart bookstack-db + sleep 15 + docker restart bookstack + ``` + +2. **Permisos incorrectos** + ```bash + docker exec bookstack ls -la /config + ``` + **Solución**: + ```bash + docker run --rm -v bookstack_config:/config alpine chown -R 1000:1000 /config + docker restart bookstack + ``` + +3. **APP_URL incorrecta** + + **Síntomas**: Redireccionamientos rotos, CSS no carga + + **Verificar**: + ```bash + docker exec bookstack cat /config/www/.env | grep APP_URL + ``` + + **Solución**: Debe coincidir con tu dominio + ```bash + # En docker-compose.yml + APP_URL: https://bookstack.tudominio.com + ``` + +### Error de Conexión a Base de Datos + +**Síntomas**: +``` +SQLSTATE[HY000] [2002] Connection refused +SQLSTATE[HY000] [1045] Access denied +``` + +**Soluciones**: + +```bash +# Verificar que MariaDB está corriendo +docker ps | grep bookstack-db + +# Verificar password en .env +cat .env | grep DB_PASSWORD + +# Verificar conexión desde BookStack +docker exec bookstack ping bookstack-db + +# Resetear conexión +docker restart bookstack-db +sleep 15 +docker restart bookstack +``` + +### Error 502 Bad Gateway (NPM/Traefik) + +**Síntomas**: Proxy no puede conectar con BookStack + +**Diagnóstico**: +```bash +# Verificar que BookStack está corriendo +docker ps | grep bookstack + +# Verificar puerto 80 +docker exec bookstack netstat -tlnp | grep 80 + +# Verificar desde proxy +docker exec npm ping bookstack +``` + +**Soluciones**: +- Verificar que BookStack está en red `proxy` +- Verificar que el contenedor se llama `bookstack` +- Reiniciar BookStack: `docker restart bookstack` + +### Lentitud Extrema + +**Diagnóstico**: +```bash +# Ver uso de CPU/RAM +docker stats bookstack bookstack-db + +# Ver queries lentas en MariaDB +docker exec bookstack-db mariadb -u bookstack -p${DB_PASSWORD} -e "SHOW FULL PROCESSLIST;" +``` + +**Soluciones**: + +1. **Limpiar caché** + ```bash + docker exec bookstack php artisan cache:clear + docker exec bookstack php artisan config:clear + docker exec bookstack php artisan view:clear + docker restart bookstack + ``` + +2. **Optimizar MariaDB** + ```bash + docker exec bookstack-db mariadb-optimize -u bookstack -p${DB_PASSWORD} bookstack + ``` + +3. **Regenerar índice de búsqueda** + ```bash + docker exec bookstack php artisan bookstack:regenerate-search + ``` + +### Error LDAP + +**Síntomas**: +``` +LDAP bind failed +Could not connect to LDAP server +``` + +**Diagnóstico**: +```bash +# Ver configuración LDAP +docker exec bookstack cat /config/www/.env | grep LDAP + +# Probar conexión LDAP +docker exec bookstack ldapsearch -x -H ldap://ldap.example.com -D "cn=bookstack,ou=Services,dc=example,dc=com" -W -b "dc=example,dc=com" "(uid=usuario)" +``` + +**Soluciones**: +- Verificar `LDAP_SERVER`, `LDAP_DN`, `LDAP_PASS` +- Verificar firewall permite conexión a puerto 389/636 +- Probar con `ldapsearch` desde el contenedor + +### Imágenes No Cargan + +**Síntomas**: Imágenes rotas, error 404 + +**Diagnóstico**: +```bash +# Ver directorio de uploads +docker exec bookstack ls -la /config/www/uploads + +# Ver permisos +docker exec bookstack stat /config/www/uploads +``` + +**Soluciones**: +```bash +# Corregir permisos +docker exec bookstack chown -R abc:abc /config/www/uploads +docker exec bookstack chmod -R 755 /config/www/uploads + +# Verificar APP_URL correcto +docker exec bookstack cat /config/www/.env | grep APP_URL +``` + +--- + +## Comandos de Emergencia + +### Reiniciar Todo + +```bash +docker restart bookstack bookstack-db +``` + +### Recrear BookStack (Mantiene Datos) + +```bash +docker stop bookstack +docker rm bookstack +docker compose up -d bookstack +``` + +### Acceso de Emergencia + +```bash +# Shell de BookStack +docker exec -it bookstack bash + +# Shell de Laravel (artisan tinker) +docker exec -it bookstack php artisan tinker + +# Ejemplo: resetear password de admin +>>> $user = \BookStack\Auth\User::where('email', 'admin@admin.com')->first(); +>>> $user->password = bcrypt('nuevapassword'); +>>> $user->save(); +``` + +### Resetear Password de Admin + +```bash +docker exec bookstack php artisan bookstack:create-admin --email=admin@admin.com +``` + +### Limpiar Todo el Caché + +```bash +docker exec bookstack php artisan optimize:clear +docker restart bookstack +``` + +--- + +## Recuperación de Desastres + +### BookStack Corrupto - Restaurar desde Backup + +```bash +# 1. Detener todo +docker stop bookstack bookstack-db + +# 2. Restaurar BD +gunzip < /backups/bookstack/bookstack-backup-FECHA.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack + +# 3. Restaurar config +docker run --rm -v bookstack_config:/restore -v /backups/bookstack:/source alpine tar xzf /source/bookstack-config-FECHA.tar.gz -C /restore + +# 4. Iniciar todo +docker start bookstack-db +sleep 15 +docker start bookstack +``` + +### MariaDB Corrupto + +```bash +# Intentar reparar +docker exec bookstack-db mariadb-check -u bookstack -p${DB_PASSWORD} --auto-repair bookstack + +# Si falla, restaurar desde backup +docker stop bookstack-db +docker volume rm bookstack_db +docker volume create bookstack_db +docker start bookstack-db +sleep 20 +gunzip < bookstack-backup.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack +``` + +--- + +## Obtener Ayuda + +### Información del Sistema + +```bash +# Versión de BookStack +docker exec bookstack php artisan --version + +# Versión de PHP +docker exec bookstack php --version + +# Versión de MariaDB +docker exec bookstack-db mariadb --version + +# Variables de entorno +docker exec bookstack env | grep -E "DB_|APP_|LDAP_" + +# Compose usado +docker inspect bookstack | grep -A 20 Labels +``` + +### Recursos Oficiales + +- [BookStack Discussions](https://github.com/BookStackApp/BookStack/discussions) +- [BookStack Discord](https://discord.gg/ztkBqR2) +- [LinuxServer Support](https://discourse.linuxserver.io/) +- [Stack Overflow](https://stackoverflow.com/questions/tagged/bookstack) + +--- + +## Prevención + +### Monitorización + +```bash +# Script de health check +#!/bin/bash +if docker exec bookstack curl -f http://localhost > /dev/null 2>&1; then + echo "✓ BookStack OK" +else + echo "✗ BookStack DOWN" + docker logs bookstack --tail 50 +fi +``` + +### Alertas + +Configura alertas en tu sistema de monitorización: + +- CPU > 80% +- RAM > 90% +- Disco > 85% +- BookStack no responde + +--- + +## Próximos Pasos + +1. **[Backup](Backup-y-Restauración)** - Automatiza backups para prevenir desastres +2. **[Actualización](Actualización)** - Mantén BookStack actualizado +3. **[Comunidad](https://github.com/BookStackApp/BookStack/discussions)** - Pregunta si no encuentras solución diff --git a/Traefik.md b/Traefik.md new file mode 100644 index 0000000..34fad8b --- /dev/null +++ b/Traefik.md @@ -0,0 +1,244 @@ +# Despliegue con Traefik + +Guía para desplegar BookStack con Traefik como proxy inverso. + +## Requisitos + +- Stack de Traefik desplegado y funcionando +- Red Docker `proxy` creada +- DNS apuntando al servidor +- Contraseña de BD generada + +--- + +## Despliegue desde Portainer + +### 1. Configurar Variables + +En Portainer, al crear el stack con **Git Repository**, configura: + +**Environment variables**: +```env +# Contraseña (generada previamente) +DB_PASSWORD=tu_password_generado + +# Base de datos (valores por defecto) +DB_NAME=bookstack +DB_USER=bookstack + +# ⚠️ IMPORTANTE para Traefik +DOMAIN_HOST=bookstack.tudominio.com +``` + +### 2. Subir Archivo Override + +En Portainer, en la sección **Additional paths**: +- Añade: `docker-compose.override.traefik.yml.example` + +O si usas **Web editor**, añade las labels manualmente al servicio `bookstack`. + +### 3. Desplegar + +Click en **Deploy the stack** y espera 1-2 minutos. + +### 4. Verificar + +- Accede a `https://bookstack.tudominio.com` +- Verifica certificado SSL (candado verde) +- Login con `admin@admin.com` / `password` +- **Cambia la contraseña inmediatamente** + +--- + +## Labels de Traefik + +El archivo `docker-compose.override.traefik.yml.example` contiene: + +```yaml +services: + bookstack: + labels: + # Habilitar Traefik + - traefik.enable=true + + # Router HTTP (redirige a HTTPS) + - traefik.http.routers.bookstack-http.rule=Host(`${DOMAIN_HOST}`) + - traefik.http.routers.bookstack-http.entrypoints=web + - traefik.http.routers.bookstack-http.middlewares=redirect-to-https + + # Router HTTPS + - traefik.http.routers.bookstack.rule=Host(`${DOMAIN_HOST}`) + - traefik.http.routers.bookstack.entrypoints=websecure + - traefik.http.routers.bookstack.tls=true + - traefik.http.routers.bookstack.tls.certresolver=letsencrypt + - traefik.http.routers.bookstack.service=bookstack-svc + - traefik.http.services.bookstack-svc.loadbalancer.server.port=80 + + # Redirect middleware + - traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https + - traefik.http.middlewares.redirect-to-https.redirectscheme.permanent=true +``` + +### Explicación de Labels + +| Label | Propósito | +|-------|-----------| +| `traefik.enable=true` | Activa Traefik para este contenedor | +| `Host(\`${DOMAIN_HOST}\`)` | Dominio que responde | +| `entrypoints=web` | Puerto 80 (HTTP) | +| `entrypoints=websecure` | Puerto 443 (HTTPS) | +| `tls.certresolver=letsencrypt` | Solicita certificado SSL automático | +| `loadbalancer.server.port=80` | Puerto interno del contenedor | +| `redirect-to-https` | Middleware para forzar HTTPS | + +--- + +## Compose Completo con Traefik + +```yaml +services: + bookstack: + container_name: bookstack + image: lscr.io/linuxserver/bookstack:latest + restart: unless-stopped + environment: + PUID: 1000 + PGID: 1000 + TZ: Europe/Madrid + APP_URL: https://${DOMAIN_HOST:-bookstack.example.com} + DB_HOST: bookstack-db + DB_PORT: 3306 + DB_DATABASE: ${DB_NAME:-bookstack} + DB_USERNAME: ${DB_USER:-bookstack} + DB_PASSWORD: ${DB_PASSWORD} + volumes: + - bookstack_config:/config + networks: + - proxy + - bookstack-internal + depends_on: + - bookstack-db + labels: + - traefik.enable=true + - traefik.http.routers.bookstack-http.rule=Host(`${DOMAIN_HOST}`) + - traefik.http.routers.bookstack-http.entrypoints=web + - traefik.http.routers.bookstack-http.middlewares=redirect-to-https + - traefik.http.routers.bookstack.rule=Host(`${DOMAIN_HOST}`) + - traefik.http.routers.bookstack.entrypoints=websecure + - traefik.http.routers.bookstack.tls=true + - traefik.http.routers.bookstack.tls.certresolver=letsencrypt + - traefik.http.routers.bookstack.service=bookstack-svc + - traefik.http.services.bookstack-svc.loadbalancer.server.port=80 + - traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https + - traefik.http.middlewares.redirect-to-https.redirectscheme.permanent=true + + bookstack-db: + container_name: bookstack-db + image: mariadb:11-alpine + restart: unless-stopped + environment: + MYSQL_DATABASE: ${DB_NAME:-bookstack} + MYSQL_USER: ${DB_USER:-bookstack} + MYSQL_PASSWORD: ${DB_PASSWORD} + MYSQL_RANDOM_ROOT_PASSWORD: 'yes' + volumes: + - bookstack_db:/var/lib/mysql + networks: + - bookstack-internal + +volumes: + bookstack_config: + name: bookstack_config + bookstack_db: + name: bookstack_db + +networks: + proxy: + external: true + bookstack-internal: + name: bookstack-internal +``` + +--- + +## Troubleshooting + +### Certificado no se genera + +**Verificar**: +```bash +# Logs de Traefik +docker logs traefik | grep bookstack +docker logs traefik | grep -i acme + +# DNS correcto +nslookup bookstack.tudominio.com +``` + +**Soluciones**: +- Verificar que `DOMAIN_HOST` está configurado +- DNS debe apuntar correctamente al servidor +- Puertos 80 y 443 abiertos en firewall +- Esperar 1-2 minutos para que Let's Encrypt valide + +### Error 404 Not Found + +**Causa**: Traefik no encuentra el contenedor + +**Verificar**: +```bash +# BookStack está en red proxy +docker inspect bookstack | grep -A 5 Networks + +# Labels están aplicados +docker inspect bookstack | grep -A 20 Labels +``` + +### Error 502 Bad Gateway + +**Causa**: BookStack no responde + +**Soluciones**: +```bash +# Ver estado de BookStack +docker logs bookstack + +# Verificar que MariaDB está lista +docker exec bookstack-db mariadb -u bookstack -p${DB_PASSWORD} -e "SELECT 1" + +# Reiniciar +docker restart bookstack-db +sleep 10 +docker restart bookstack +``` + +--- + +## Configuración Avanzada + +### Headers de Seguridad + +Añade headers adicionales con middleware: + +```yaml +labels: + - traefik.http.routers.bookstack.middlewares=bookstack-headers + - traefik.http.middlewares.bookstack-headers.headers.customResponseHeaders.X-Robots-Tag=none + - traefik.http.middlewares.bookstack-headers.headers.sslProxyHeaders.X-Forwarded-Proto=https +``` + +### Limitar Acceso por IP + +```yaml +labels: + - traefik.http.routers.bookstack.middlewares=bookstack-ipwhitelist + - traefik.http.middlewares.bookstack-ipwhitelist.ipwhitelist.sourcerange=192.168.1.0/24,10.0.0.0/8 +``` + +--- + +## Próximos Pasos + +1. **[Configuración Inicial](Configuración-Inicial)** - Configurar BookStack +2. **[Personalización](Personalización)** - LDAP, temas +3. **[Backup](Backup-y-Restauración)** - Automatiza backups diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 0000000..ed6cd8f --- /dev/null +++ b/_Sidebar.md @@ -0,0 +1,17 @@ +## BookStack Wiki + +### 🚀 Inicio +- [Home](Home) + +### 📦 Despliegue +- [Traefik](Traefik) +- [NPM](NPM) + +### ⚙️ Configuración +- [Configuración Inicial](Configuración-Inicial) +- [Personalización](Personalización) + +### 💾 Mantenimiento +- [Backup y Restauración](Backup-y-Restauración) +- [Actualización](Actualización) +- [Solución de Problemas](Solución-de-Problemas)