This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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:

# 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:

docker restart bookstack

Active Directory

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

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, Azure AD)

Azure AD (Microsoft Entra ID)

Registra aplicación en Azure Portal → Azure Active Directory → App registrations
New registration:
- Name: BookStack
- Supported account types: Single tenant
- Redirect URI: https://bookstack.tudominio.com/login/service/azure/callback
Anota Application (client) ID y Directory (tenant) ID
En Certificates & secrets, crea New client secret y anótalo
En API permissions, añade:
- Microsoft Graph → Delegated permissions → User.Read, email, openid, profile
- Click Grant admin consent

Añade al .env:

# Azure AD OAuth
AZURE_TENANT=tu-tenant-id
AZURE_APP_ID=tu-application-client-id
AZURE_APP_SECRET=tu-client-secret
AZURE_AUTO_REGISTER=true
AZURE_AUTO_CONFIRM_EMAIL=true

Reinicia:

docker restart bookstack

Opciones adicionales:

# Sincronizar grupos de Azure AD (opcional)
AZURE_USER_TO_GROUPS=true
AZURE_GROUPS_CLAIM=groups
AZURE_REMOVE_FROM_GROUPS=true

ℹ️ Nota: Para sincronización de grupos, añade en Azure AD Token configuration el claim groups.

Google OAuth

Crea aplicación OAuth en Google Cloud Console
Añade al .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

AUTH_METHOD=github
GITHUB_APP_ID=tu-client-id
GITHUB_APP_SECRET=tu-client-secret

GitLab OAuth

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:

<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

<script>
  // Añadir mensaje de bienvenida
  document.addEventListener('DOMContentLoaded', function() {
    console.log('Wiki Corporativa - Documentación Técnica');
  });
</script>

Comandos Útiles

Acceder al Contenedor

# Shell
docker exec -it bookstack bash

# Ver comandos artisan disponibles
docker exec bookstack php artisan list

Limpiar Caché

# 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

docker exec bookstack php artisan bookstack:regenerate-search

Limpiar Sesiones Antiguas

docker exec bookstack php artisan bookstack:cleanup-sessions

API REST

Habilitar API

Settings → Settings → Enable API

Crear Token de API

Settings → Users → Selecciona usuario
API Tokens → Create Token
Token Name: Script de Backup
Expiry Date: Fecha de expiración (opcional)
Save y copia el token

Ejemplo de Uso

# 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

- 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

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']}")