Files

groales 3a2976ac7b Añadir sección de despliegue con Docker CLI

2025-12-05 10:15:57 +01:00

16 KiB

Raw Permalink Blame History

BookStack

Plataforma de documentación y wiki de código abierto. Organiza contenido en libros, capítulos y páginas con editor WYSIWYG y Markdown.

Características

📚 Organización jerárquica: Libros → Capítulos → Páginas
✏️ Editor dual: WYSIWYG y Markdown
🔍 Búsqueda potente: Busca en todo el 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, OAuth
🌍 Multi-idioma: Soporte para múltiples idiomas

Requisitos Previos

Docker Engine instalado
Portainer configurado (recomendado)
Para Traefik o NPM: Red Docker proxy creada
Dominio configurado: Para acceso HTTPS
Contraseña generada: DB_PASSWORD

⚠️ IMPORTANTE: BookStack requiere MariaDB. Este compose incluye el contenedor de base de datos.

Generar Claves y Contraseñas

Antes de cualquier despliegue, genera las claves necesarias:

# APP_KEY (BookStack)
docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

# DB_PASSWORD (MariaDB)
openssl rand -base64 32

Guarda los resultados, los necesitarás en el archivo .env.

⚠️ Importante: Usa comillas simples en el archivo .env si la contraseña contiene caracteres especiales. Ejemplo: DB_PASSWORD='tu_password_generado'

Despliegue con Portainer

Opción A: Git Repository (Recomendada)

Permite mantener la configuración actualizada automáticamente desde Git.

En Portainer, ve a Stacks → Add stack
Nombra el stack: bookstack
Selecciona Git Repository
Configura:
- Repository URL: https://git.ictiberia.com/groales/bookstack
- Repository reference: refs/heads/main
- Compose path: docker-compose.yml
- GitOps updates: Activado (opcional - auto-actualización)
Solo para Traefik: En Additional paths, añade:
- docker-compose.override.traefik.yml.example
En Environment variables, añade:

APP_KEY=base64:tu_clave_generada
DB_PASSWORD=tu_password_generado
DOMAIN_HOST=bookstack.tudominio.com

Click en Deploy the stack

Opción B: Web editor

Para personalización completa del compose.

En Portainer, ve a Stacks → Add stack
Nombra el stack: bookstack
Selecciona Web editor
Pega el contenido de docker-compose.yml
En Environment variables, añade las mismas variables que la Opción A
Click en Deploy the stack

Despliegue con Docker CLI

Si prefieres trabajar desde la línea de comandos:

1. Clonar el repositorio

git clone https://git.ictiberia.com/groales/bookstack.git
cd bookstack

2. Generar APP_KEY y contraseña

APP_KEY (requerido por BookStack):

docker run --rm lscr.io/linuxserver/bookstack:latest php /app/www/artisan key:generate --show

Salida esperada: base64:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=

DB_PASSWORD (contraseña de MariaDB):

openssl rand -base64 32

3. Elegir modo de despliegue

Opción A: Traefik (recomendado para producción)

cp docker-compose.override.traefik.yml.example docker-compose.override.yml
cp .env.example .env
nano .env  # Editar: pegar APP_KEY, DB_PASSWORD, configurar DOMAIN_HOST

⚠️ IMPORTANTE: DOMAIN_HOST es obligatoria en todos los casos (BookStack la usa en APP_URL).

Opción B: Nginx Proxy Manager

cp .env.example .env
nano .env  # Editar: pegar APP_KEY, DB_PASSWORD, configurar DOMAIN_HOST

4. Iniciar el servicio

docker compose up -d

La inicialización puede tardar 30-60 segundos (MariaDB + BookStack migrations).

5. Verificar el despliegue

# Ver logs en tiempo real
docker compose logs -f bookstack

# Verificar contenedores activos
docker compose ps

# Comprobar base de datos
docker compose exec bookstack-db mysql -ubookstack -p$DB_PASSWORD -e "SHOW DATABASES;"

Acceso:

Traefik: https://<DOMAIN_HOST> (ejemplo: https://bookstack.example.com)
NPM: Configurar en NPM apuntando a bookstack puerto 80

Credenciales iniciales (⚠️ CRÍTICO: cambiar inmediatamente):

Email: admin@admin.com
Contraseña: password

Después del primer login:

Ir a Settings → Users
Editar usuario Admin
Cambiar email y contraseña
O eliminar y crear usuario propio

Modos de Despliegue

Traefik (Proxy Inverso con SSL automático)

Requisitos:

Stack de Traefik desplegado
Red proxy creada
DNS apuntando al servidor

Si desplegaste con Opción A (Git Repository), ya configuraste todo en el paso 5 y 6. Simplemente accede a https://bookstack.tudominio.com

Si usas otra forma de despliegue:

Asegúrate de tener el archivo docker-compose.override.traefik.yml.example como docker-compose.override.yml
Verifica que en Environment variables tienes DOMAIN_HOST configurado correctamente
Despliega el stack y accede a https://bookstack.tudominio.com

Ejemplo de compose completo con Traefik:

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}
      APP_KEY: ${APP_KEY}
      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:12
    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

Nginx Proxy Manager (NPM)

Requisitos:

NPM desplegado y accesible
Red proxy creada
DNS apuntando al servidor

Pasos:

Despliega el stack con el docker-compose.yml base (sin override)
En NPM, crea un nuevo Proxy Host:
- Domain Names: bookstack.tudominio.com
- Scheme: http
- Forward Hostname / IP: bookstack
- Forward Port: 80
- Cache Assets: ✅ Activado
- Block Common Exploits: ✅ Activado
- Websockets Support: ✅ Activado
En la pestaña SSL:
- SSL Certificate: Request a new SSL Certificate (Let's Encrypt)
- Force SSL: ✅ Activado
- HTTP/2 Support: ✅ Activado
- HSTS Enabled: ✅ Activado (opcional)
Guarda y accede a https://bookstack.tudominio.com

Configuración Inicial

Primer Acceso

Accede a BookStack usando tu dominio configurado
Login con credenciales por defecto:
- Email: admin@admin.com
- Password: password
⚠️ CRÍTICO: Cambia la contraseña inmediatamente:
- Click en tu avatar (esquina superior derecha)
- Edit Profile → Change Password

Panel de Administración

Accede al panel: Settings (engranaje superior derecho)

Configuración Básica

Settings → Settings:

Application Name: Nombre de tu wiki
Application Description: Descripción breve
Application Logo: Sube tu logo personalizado
Default Language: Español u otro idioma

Registro de Usuarios

Settings → Registration Settings:

Allow public registration: Desactivar (❌)
Allow public viewing: Activar si quieres que usuarios no autenticados puedan leer
Default role for new users: Seleccionar rol apropiado

Roles y Permisos

Settings → Roles:

Admin: Control total
Editor: Puede crear y editar contenido
Viewer: Solo lectura

Crea roles personalizados según necesites:

Permissions: Granular por libros, capítulos, páginas
System Permissions: Gestión de imágenes, ajustes

Personalización de Tema

Settings → Customization:

Custom HTML Head Content: Añadir CSS personalizado
Color Scheme: Claro/Oscuro
Custom Styles: CSS para personalización avanzada

Personalización

Integración con LDAP

Settings → Authentication → LDAP:

# Añadir al .env
LDAP_SERVER=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_USER_FILTER=(&(uid=${user}))
LDAP_VERSION=3

Reinicia el contenedor: docker restart bookstack

SAML / OAuth

Settings → Authentication:

SAML 2.0: Para Active Directory con ADFS
OAuth: Google, GitHub, GitLab, etc.

Consulta la documentación oficial para configuración específica.

Comandos Personalizados

Acceso al contenedor:

# Shell de BookStack
docker exec -it bookstack bash

# Comandos artisan disponibles
docker exec bookstack php artisan list

# Limpiar caché
docker exec bookstack php artisan cache:clear

# Regenerar permisos de búsqueda
docker exec bookstack php artisan bookstack:regenerate-search

Backup y Restauración

Backup Manual

# Backup de MariaDB
docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack > bookstack-backup-$(date +%Y%m%d).sql

# Backup de configuración y uploads
docker run --rm -v bookstack_config:/backup -v $(pwd):/target alpine tar czf /target/bookstack-config-$(date +%Y%m%d).tar.gz -C /backup .

Backup Automático

Crea un script en /root/backup-bookstack.sh:

#!/bin/bash
BACKUP_DIR="/backups/bookstack"
DATE=$(date +%Y%m%d-%H%M%S)
DB_PASSWORD="tu_password_aqui"

mkdir -p $BACKUP_DIR

# MariaDB
docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack | gzip > $BACKUP_DIR/bookstack-db-$DATE.sql.gz

# Configuración
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 (mantener 7 días)
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

echo "Backup completado: $DATE"

Programa con cron:

chmod +x /root/backup-bookstack.sh
crontab -e

# Backup diario a las 2 AM
0 2 * * * /root/backup-bookstack.sh

Restauración

# Detener BookStack
docker stop bookstack

# Restaurar MariaDB
gunzip < bookstack-db-20250101.sql.gz | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack

# Restaurar configuración
docker run --rm -v bookstack_config:/restore -v $(pwd):/source alpine tar xzf /source/bookstack-config-20250101.tar.gz -C /restore

# Iniciar BookStack
docker start bookstack

Actualización

Actualizar BookStack

# 1. Backup ANTES de actualizar
docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack > bookstack-pre-update-$(date +%Y%m%d).sql

# 2. Detener stack
docker stop bookstack bookstack-db

# 3. Actualizar imágenes
docker pull lscr.io/linuxserver/bookstack:latest
docker pull mariadb:12

# 4. Iniciar stack
docker start bookstack-db
sleep 10
docker start bookstack

# 5. Verificar logs
docker logs -f bookstack

# 6. Verificar versión en Settings → About

Actualizar MariaDB

Si necesitas actualizar de MariaDB 10 a 11 (ya está en 11):

# 1. Backup
docker exec bookstack-db mariadb-dump -u bookstack -p${DB_PASSWORD} bookstack > bookstack-db-migration.sql

# 2. Detener y eliminar contenedor antiguo
docker stop bookstack-db
docker rm bookstack-db

# 3. Eliminar volumen antiguo
docker volume rm bookstack_db

# 4. Recrear con MariaDB 12
docker compose up -d bookstack-db

# 5. Esperar inicialización
sleep 15

# 6. Restaurar datos
cat bookstack-db-migration.sql | docker exec -i bookstack-db mariadb -u bookstack -p${DB_PASSWORD} bookstack

# 7. Iniciar BookStack
docker start bookstack

Solución de Problemas

BookStack no inicia

Síntomas: Contenedor se reinicia constantemente

Diagnóstico:

docker logs bookstack

Soluciones:

Verificar que MariaDB esté funcionando: docker logs bookstack-db
Comprobar contraseña en .env
Verificar permisos del volumen: docker exec bookstack ls -la /config

Error de conexión a base de datos

Síntomas: SQLSTATE[HY000] [2002] Connection refused

Solución:

# Verificar que MariaDB esté lista
docker exec bookstack-db mariadb -u bookstack -p${DB_PASSWORD} -e "SELECT 1"

# Reiniciar servicios en orden
docker restart bookstack-db
sleep 10
docker restart bookstack

Error de permisos

Síntomas: PermissionError: [Errno 13] Permission denied