BookStack es una de las formas más ordenadas de tener tu propia wiki de documentación, y con Docker se instala en cuestión de minutos. En esta guía levantas la aplicación junto a una base de datos MariaDB usando un solo archivo docker-compose.yml, aprendes a generar la clave APP_KEY, a configurar la variable crítica APP_URL, a publicarlo con HTTPS detrás de un proxy inverso y a hacer copias de seguridad. La misma explicación está disponible en inglés.

Puntos clave

  • BookStack es una plataforma de documentación de código abierto escrita en PHP con el framework Laravel; su primer lanzamiento fue en julio de 2015 y hoy va por la versión CalVer v26.05.
  • Organiza el contenido en cuatro niveles: estanterías, libros, capítulos y páginas, lo que facilita mantener una base de conocimiento ordenada.
  • El montaje recomendado usa la imagen lscr.io/linuxserver/bookstack de LinuxServer junto a un contenedor MariaDB; BookStack no funciona con SQLite.
  • Dos variables son imprescindibles: APP_URL (la dirección exacta desde la que accedes) y APP_KEY (una clave base64: que debes generar antes de arrancar).
  • Fija una versión concreta de la imagen (por ejemplo version-v26.05.2) en lugar de :latest; así controlas cuándo saltas de versión y evitas sorpresas al reiniciar.

¿Qué es BookStack y para qué sirve?

BookStack es una plataforma wiki de documentación de código abierto, pensada para que equipos y particulares mantengan una base de conocimiento clara y con buscador propio. Nació en julio de 2015 de la mano de Dan Brown y está construida sobre el framework PHP Laravel, con licencia MIT. Es la alternativa autoalojada natural a herramientas comerciales como Confluence o Notion.

Su gran virtud es la sencillez: en lugar de darte una página en blanco, te impone una estructura que invita a documentar de forma coherente. Incluye editor visual (WYSIWYG) y también editor Markdown, control de permisos por rol, historial de versiones de cada página, búsqueda de texto completo, comentarios y diagramas con drawio integrado. Todo el contenido queda en tu servidor, sin depender de una nube ajena.

¿Cómo organiza BookStack la documentación?

Aquí está la idea que diferencia a BookStack de un wiki tradicional: una jerarquía fija de cuatro niveles. De mayor a menor, son estanterías (shelves), libros (books), capítulos (chapters) y páginas (pages).

  • La página es la unidad de contenido, donde escribes de verdad.
  • El capítulo agrupa páginas relacionadas dentro de un libro (es opcional).
  • El libro es el contenedor principal de un tema; reúne capítulos y páginas.
  • La estantería agrupa varios libros afines, como una colección temática.

Un mismo libro puede aparecer en varias estanterías, así que la organización es flexible aunque los niveles sean fijos. Esta estructura es justo lo que evita el caos típico de los wikis que crecen sin orden, y hace que el buscador y los permisos resulten muy predecibles.

El docker-compose.yml con la imagen de LinuxServer

Antes de escribir el Compose necesitas una máquina Linux con Docker y el plugin Compose instalados; si aún no los tienes, sigue primero la guía para instalar Docker en Ubuntu 24.04. El primer paso propio de BookStack es generar la APP_KEY, una clave de cifrado que Laravel usa para las sesiones y las cookies. La imagen de LinuxServer trae una utilidad para crearla:

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:version-v26.05.2 appkey

El comando imprime una cadena con el formato base64:.... Cópiala entera, porque la pegarás en el Compose. Ahora crea una carpeta para el proyecto y guarda dentro este docker-compose.yml, sustituyendo las claves de ejemplo y la APP_URL por tus valores reales:

services:
  bookstack_db:
    image: mariadb:11.4
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: cambia_esta_clave_root
      MYSQL_DATABASE: bookstackapp
      MYSQL_USER: bookstack
      MYSQL_PASSWORD: cambia_esta_clave
      MYSQL_INITDB_SKIP_TZINFO: "yes"
    volumes:
      - bookstack_db_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 30s
      timeout: 5s
      retries: 5

  bookstack:
    image: lscr.io/linuxserver/bookstack:version-v26.05.2
    restart: unless-stopped
    depends_on:
      bookstack_db:
        condition: service_healthy
    ports:
      - "6875:80"
    environment:
      PUID: 1000
      PGID: 1000
      TZ: Europe/Madrid
      APP_URL: http://192.168.1.10:6875
      APP_KEY: base64:pega_aqui_la_clave_generada
      DB_HOST: bookstack_db
      DB_PORT: 3306
      DB_DATABASE: bookstackapp
      DB_USERNAME: bookstack
      DB_PASSWORD: cambia_esta_clave
    volumes:
      - bookstack_config:/config

volumes:
  bookstack_db_data:
  bookstack_config:

Fíjate en algunos detalles. BookStack no arranca hasta que la base de datos pasa su healthcheck, gracias a depends_on con la condición service_healthy. El puerto 80 del contenedor se publica en el 6875 del anfitrión (la convención de la imagen), así que la wiki quedará en la dirección que hayas puesto en APP_URL. Y toda la configuración persistente vive en el volumen bookstack_config, montado en /config.

Con el archivo listo, arranca la pila en segundo plano y observa el registro del contenedor:

docker compose up -d
docker compose ps
docker compose logs -f bookstack

La primera vez, la imagen prepara la base de datos y aplica las migraciones de Laravel, por lo que el arranque tarda un poco más. Cuando el registro se detenga, abre la APP_URL en el navegador. El usuario inicial es admin@admin.com con contraseña password; cámbialos en cuanto entres, desde Configuración → Usuarios.

¿Qué variables de entorno son imprescindibles?

De todas las variables, dos deciden si BookStack funciona o no. La primera es APP_KEY, la clave de cifrado que ya generaste: sin ella, la aplicación ni siquiera arranca. La segunda, y la fuente número uno de problemas, es APP_URL.

APP_URL debe ser exactamente la dirección desde la que accedes a BookStack, con su protocolo y su puerto: por ejemplo http://192.168.1.10:6875 en red local, o https://docs.midominio.com si lo publicas con dominio. Si esta variable no coincide con la URL real, verás la interfaz sin estilos, los enlaces romperán y el inicio de sesión fallará, porque Laravel genera todas las rutas absolutas a partir de ella. Es el motivo más común de un BookStack que se ve mal.

Si más adelante cambias de dirección (por ejemplo, al pasar de IP a dominio con HTTPS), no basta con editar la variable: hay que reescribir las URL guardadas en la base de datos con el comando de mantenimiento que trae la aplicación:

docker exec -it bookstack php /app/www/artisan bookstack:update-url http://192.168.1.10:6875 https://docs.midominio.com

¿Cómo publicarlo con un proxy inverso?

Servir BookStack por HTTP plano en red local está bien para pruebas, pero para sacarlo a Internet necesitas cifrado. La forma habitual es ponerlo detrás de un proxy inverso que gestione el certificado TLS por ti. Tienes dos opciones muy usadas en esta serie: Nginx Proxy Manager, con su interfaz web para crear el proxy y pedir el certificado de Let’s Encrypt con un par de clics, o Traefik, que se configura por etiquetas en el propio Compose.

Si usas Traefik, quita la sección ports del servicio bookstack, conéctalo a la red del proxy y añádele estas etiquetas:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.bookstack.rule=Host(`docs.midominio.com`)"
      - "traefik.http.routers.bookstack.entrypoints=websecure"
      - "traefik.http.routers.bookstack.tls.certresolver=le"
      - "traefik.http.services.bookstack.loadbalancer.server.port=80"

Sea cual sea el proxy, recuerda actualizar APP_URL a la dirección https:// final y, si ya habías arrancado con otra URL, ejecutar el comando bookstack:update-url del apartado anterior para que todos los enlaces internos apunten al dominio correcto.

¿Cómo hago copias de seguridad?

Una copia de seguridad completa de BookStack tiene dos piezas: el volcado de la base de datos y el volumen /config (que guarda las imágenes subidas, los adjuntos y la propia APP_KEY). Empieza por exportar la base de datos con mariadb-dump:

docker compose exec bookstack_db mariadb-dump -u bookstack -pcambia_esta_clave bookstackapp > bookstack-db.sql

Después respalda el volumen bookstack_config con la herramienta que prefieras; en esta serie lo automatizamos más adelante con Duplicati. Para actualizar BookStack a una versión nueva, cambia la etiqueta de la imagen y recrea el contenedor:

docker compose pull
docker compose up -d

La imagen aplica las migraciones de base de datos necesarias al arrancar. Como BookStack publica una versión de funcionalidades cada dos meses, conviene leer las notas de la versión antes de saltar varias de golpe, y tener siempre a mano la copia de la base de datos por si necesitas volver atrás.

Preguntas frecuentes

¿BookStack necesita una base de datos aparte?

Sí. A diferencia de otras aplicaciones ligeras, BookStack no incluye SQLite: requiere una base de datos MariaDB o MySQL para funcionar. Por eso el docker-compose.yml define dos servicios, la aplicación y bookstack_db. Puedes reutilizar una instancia de MariaDB que ya tengas, siempre que crees una base de datos y un usuario dedicados y apuntes ahí las variables DB_HOST, DB_DATABASE, DB_USERNAME y DB_PASSWORD.

¿Por qué la interfaz se ve rota o no puedo iniciar sesión?

Casi siempre es un problema de APP_URL. Si esa variable no coincide con la dirección exacta desde la que abres BookStack (protocolo, IP o dominio y puerto incluidos), Laravel genera enlaces y recursos hacia una URL equivocada: la página aparece sin estilos y el login falla. Corrige APP_URL, y si ya habías guardado contenido con otra dirección, ejecuta el comando bookstack:update-url para reescribir las rutas.

¿En qué se diferencia BookStack de Wiki.js?

BookStack impone una jerarquía fija de estanterías, libros, capítulos y páginas, ideal para documentación estructurada y equipos que quieren orden desde el principio. Wiki.js es más flexible y técnico: organiza el contenido en un árbol libre de rutas, admite varios motores de almacenamiento y se integra con Git. Si buscas sencillez y estructura, BookStack; si necesitas control fino sobre la organización, Wiki.js.

Conclusión

Con un único docker-compose.yml tienes una wiki de documentación completa: aplicación, base de datos y almacenamiento persistente, todo en tu servidor. La clave está en generar bien la APP_KEY y en clavar la APP_URL; con esas dos variables correctas, el resto fluye. El siguiente paso lógico es sacarla a Internet con seguridad detrás de Nginx Proxy Manager o Traefik y programar copias de seguridad periódicas de la base de datos y del volumen /config.

Fuentes

  1. Documentación oficial de BookStack
  2. Repositorio de BookStack en GitHub
  3. Imagen Docker de BookStack en LinuxServer

Ruta: Productividad y documentos self-hosted con Docker