Wiki completa de BookStack: 9 páginas en español
- Home: Índice, características, arquitectura MariaDB - Traefik: Despliegue con labels, troubleshooting - NPM: Despliegue con Proxy Hosts, comparativa - Configuración Inicial: Primer acceso (admin@admin.com), roles, organización - Personalización: LDAP/SAML/OAuth, temas, API, integraciones - Backup y Restauración: mariadb-dump, scripts automáticos, migración - Actualización: BookStack updates, MariaDB 10→11 migration, rollback - Solución de Problemas: Diagnóstico, errores comunes, recuperación - Sidebar: Navegación completa
245
Actualización.md
Normal file
245
Actualización.md
Normal file
@@ -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
|
||||
189
Backup-y-Restauración.md
Normal file
189
Backup-y-Restauración.md
Normal file
@@ -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
|
||||
206
Configuración-Inicial.md
Normal file
206
Configuración-Inicial.md
Normal file
@@ -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
|
||||
<style>
|
||||
:root {
|
||||
--color-primary: #0066cc;
|
||||
}
|
||||
.header-links {
|
||||
background-color: #0066cc;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
150
Home.md
150
Home.md
@@ -1 +1,149 @@
|
||||
¡Bienvenidos a la Wiki!
|
||||
# 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)
|
||||
|
||||
99
NPM.md
Normal file
99
NPM.md
Normal file
@@ -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
|
||||
264
Personalización.md
Normal file
264
Personalización.md
Normal file
@@ -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
|
||||
<style>
|
||||
/* Tema oscuro personalizado */
|
||||
:root {
|
||||
--color-primary: #1e88e5;
|
||||
--color-primary-light: #64b5f6;
|
||||
--color-link: #42a5f5;
|
||||
}
|
||||
|
||||
/* Header personalizado */
|
||||
.header {
|
||||
background: linear-gradient(90deg, #1e3c72 0%, #2a5298 100%);
|
||||
}
|
||||
|
||||
/* Logo más grande */
|
||||
.logo-image {
|
||||
max-height: 50px;
|
||||
}
|
||||
|
||||
/* Ocultar "Powered by BookStack" */
|
||||
.text-muted {
|
||||
display: none;
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
### JavaScript Personalizado
|
||||
|
||||
```html
|
||||
<script>
|
||||
// Añadir mensaje de bienvenida
|
||||
document.addEventListener('DOMContentLoaded', function() {
|
||||
console.log('Wiki Corporativa - Documentación Técnica');
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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": "<p>Contenido</p>"}' \
|
||||
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: "<p>Generado por Ansible</p>"
|
||||
```
|
||||
|
||||
### 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`
|
||||
355
Solución-de-Problemas.md
Normal file
355
Solución-de-Problemas.md
Normal file
@@ -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
|
||||
244
Traefik.md
Normal file
244
Traefik.md
Normal file
@@ -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
|
||||
17
_Sidebar.md
Normal file
17
_Sidebar.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user