Skip to main content

BookStack

bookstack-hero-screenshot.webp

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.

  1. En Portainer, ve a Stacks → Add stack
  2. Nombra el stack: bookstack
  3. Selecciona Git Repository
  4. 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)
  5. Solo para Traefik: En Additional paths, añade:
    • docker-compose.override.traefik.yml.example
  6. En Environment variables, añade:
APP_KEY=base64:tu_clave_generada
DB_PASSWORD=tu_password_generado
DOMAIN_HOST=bookstack.tudominio.com
  1. Click en Deploy the stack

Opción B: Web editor

Para personalización completa del compose.

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

FxR2-15-docker-add-stack-web-editor.gif

docker-compose

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

  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

Variables

# === VARIABLES REQUERIDAS ===
# Generar con: docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
APP_KEY=''

# Generar DB_PASSWORD con: openssl rand -base64 32
DB_PASSWORD=''

# Dominio completo para APP_URL
DOMAIN_HOST=bookstack.example.com

# === CONFIGURACIÓN OPCIONAL ===
# Base de datos (valores por defecto)
DB_NAME=bookstack
DB_USER=bookstack

# SMTP enviroment variables 
MAIL_DRIVER=smtp
MAIL_HOST=smtp.office365.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=Usuario_Microsoft
MAIL_PASSWORD=Password
MAIL_FROM=noreply@dominio.com
MAIL_FROM_NAME=BookStack

# AzureAD (Microsoft)
# Replace '{APP_ID}', '{APP_SECRET}' and '{TENANT}' values with Azure APP_ID and APP_SECRET and TENANT
AZURE_TENANT={TENANT}
AZURE_APP_ID={APP_ID}
AZURE_APP_SECRET={APP_SECRET}

Publicando detrás de un proxy

Crear registro DNS

En el proveedor que aloja el servidor DNS público, crear un registro DNS que resuelva la IP pública que llega al Proxy hacia un nombre del estilo "host.domain.com"

NGINX proxy

image.png

Para publicar el contenedor detrás de NGINX proxy, como el stack está en la red proxy solo deberás crear un nuevo host

Crear un nuevo "proxy host"

Añade un nuevo proxy host con el nombre de dominio creado en el paso anterior redirigido hacia el nombre del contenedor y el puerto que use:

image.png

Publicando con Traefik

traefik-concepts-1.webp

Para publicar el contenedor detrás del proxy Traefik, deberás añadir al fichero docker-compose.yaml las siguientes etiquetas al servicio bookstack

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

En este punto ya puedes ir a APP_URL=http://bookstack.tudominio.com y validarte:

Cambia la los datos de acceso cuanto antes

SSO

Microsoft EntraID

Registro de aplicación

  1. Inicie sesión en el Centro de administración de Microsoft Entra 

  2. Entra ID->Registros de Aplicaciones y seleccione Nuevo registro.

  3. Escriba un nombre descriptivo para la aplicación.

  4. En Tipos de cuenta admitidos, especifique quién puede usar la aplicación. Se recomienda seleccionar solo Cuentas en este directorio organizativo para la mayoría de las aplicaciones.

  5. URI de redirección: WEB ->  https://app.dominio.com/user/oauth2/EntraID/callback

image.png

Secreto de aplicación

  1. Seleccione Certificados y secretos>Secretos de cliente>Nuevo secreto de cliente.

  2. Agregue una descripción para la clave secreta de cliente.

  3. Seleccione una expiración para el secreto o especifique una duración personalizada.

  4. Registre el valor del secreto de cliente para usarlo en el código de la aplicación cliente. Este valor secreto nunca se muestra de nuevo después de salir de esta página.

image.png

Bookstack

Back to top