Cómo instalar BookStack en Debian 12

BookStack es un software wiki gratuito y de código abierto escrito en PHP con el framework web Laravel. BookStack pretende ser una plataforma sencilla y autoalojada para almacenar y organizar información.

En este tutorial, te guiaremos paso a paso por el proceso de instalación de BookStack en el servidor Debian 12 para que puedas tener tu propia plataforma tipo wiki para publicar información.

Requisitos previos

Antes de empezar, asegúrate de que tienes lo siguiente:

• Un servidor Debian 12.
• Un usuario no root con privilegios de administrador sudo.
• Un nombre de dominio apuntando a la dirección IP del servidor.

Instalación de las dependencias

BookStack es una plataforma wiki escrita en PHP y MySQL/MariaDB. En este momento, es totalmente compatible con PHP 8.2. En esta fase, instalarás las dependencias para BookStack, que incluyen los paquetes LAMP Stack (Apache2, MariaDB, PHP), Git y Composer.

Actualiza y refresca el índice de paquetes de Debian utilizando el siguiente comando.

sudo apt update

Una vez actualizado el repositorio, instala las dependencias de los paquetes para BookStack ejecutando el siguiente comando apt install. Con este comando, instalarás el paquete LAMP Stack, Composer y Git.

sudo apt install apache2 mariadb-server composer curl php php-xml libapache2-mod-php php-fpm php-curl php-mbstring php-ldap php-tidy php-zip php-gd php-mysql git

Escribe y para proceder con la instalación.

Una vez instaladas las dependencias, verifica cada una de ellas ejecutando el siguiente comando.

Verifica el servicio apache2 mediante el siguiente comando systemctl para asegurarte de que el servicio se está ejecutando y está habilitado.

sudo systemctl is-enabled apache2
sudo systemctl status apache2

La siguiente salida confirmará que el servicio apache2 se está ejecutando y está habilitado.

Ahora verifica el servicio mariadb mediante el comando siguiente.

sudo systemctl is-enabled mariadb
sudo systemctl status mariadb

La salida debería mostrar que el servicio mariadb se está ejecutando y está habilitado en tu sistema.

A continuación, comprueba la versión de PHP y la lista de extensiones habilitadas mediante el siguiente comando.

php -v
php -m

Según la siguiente salida, PHP 8.2 está instalado en tu sistema.

Por último, verifica el Composer utilizando el siguiente comando. Esto localizará el archivo binario de Composer y comprobará su versión.

which composer
sudo -u www-data composer -v

Deberías ver que Composer 2.5.5 está instalado en /usr/bin/composer.

Configurar PHP

Tras instalar las dependencias, el siguiente paso es configurar la instalación de PHP realizando cambios en el archivo php.ini de tu máquina Debian.

Abre la configuración por defecto de PHP /etc/php/8.2/apache2/php.ini utilizando el siguiente comando del editor nano.

sudo nano /etc/php/8.2/apache2/php.ini

Cambia algunos ajustes por defecto con la siguiente configuración. Asegúrate de ajustar los parámetros date.timezone y memory_limit con el entorno de tu servidor.

date.timezone = Europe/Amsterdam
memory_limit = 512M

Guarda el archivo y sal del editor cuando hayas terminado.

Ahora ejecuta el siguiente comando systemctl para reiniciar el servicio apache2 y aplicar los cambios que has realizado.

sudo systemctl restart apache2

Configurar el servidor MariaDB

Ahora que PHP está configurado, el siguiente paso será configurar la instalación del servidor MariaDB utilizando la utilidad mariadb-secure-installation, que te permite configurar la seguridad básica para MariaDB. Además, crearás una nueva base de datos y un nuevo usuario que utilizará BookStack.

Ejecuta el siguiente comando mariadb-secure-installlation para asegurar tu instalación de MariaDB.

sudo mariadb-secure-installation

Durante el proceso, se te preguntarán algunas configuraciones. Escribe Y para aceptar y aplicar los nuevos cambios, o escribe n para No rechazar la configuración.

• Para la instalación por defecto del servidor MariaDB sin contraseña de root, pulsa ENTER cuando se te pregunte por la contraseña.
• La autenticación local para los usuarios root de MariaDB está asegurada por defecto, introduce ‘n’ cuando se te pregunte si quieres cambiar el método de autenticación a ‘unix_socket’.
• Introduce «Y» para crear una nueva contraseña de root de MariaDB. A continuación, introduce la contraseña segura de tu usuario raíz de MariaDB y repite la operación.
• Cuando se te pida que desactives la autenticación remota para el usuario raíz de MariaDB, introduce «Y» para aceptar.
• La instalación por defecto del servidor MariaDB viene con la base de datos «test» y permite que un usuario anónimo acceda a ella. Introduce «Y» en ambas opciones para eliminar la base de datos «test» por defecto y el privilegio anónimo.
• Por último, introduce «Y» para confirmar los privilegios de recarga de tablas.

Después de configurar MariaDB, crearás una nueva base de datos MariaDB y un nuevo usuario que utilizará BookStack mediante el comando cliente mariadb.

Accede al servidor MariaDB utilizando el siguiente comando mariadb. Introduce tu contraseña de root de MariaDB cuando te lo pida.

sudo mariadb -u root -p

Ahora ejecuta las siguientes consultas para crear una nueva base de datos y un nuevo usuario para BookStack. En este ejemplo, crearás una nueva base de datos y un nuevo usuario bookstack, con la contraseña p4ssword.

CREATE DATABASE bookstack;
CREATE USER bookstack@localhost IDENTIFIED BY 'p4ssword';
GRANT ALL ON bookstack.* TO bookstack@localhost WITH GRANT OPTION;
FLUSH PRIVILEGES;

A continuación, ejecuta la siguiente consulta para verificar los privilegios del usuario bookstack.

SHOW GRANTS FOR bookstack@localhost;

Deberías ver que el usuario bookstack tiene permiso para acceder y gestionar la base de datos bookstack que utilizará BookStack.

Escribe quit para salir del Servidor MariaDB.

Descargar Bookstack

Ahora que has configurado el servidor PHP y MariaDB, estás listo para instalar BookStack. En esta sección, instalarás BookStack a través de Git y Composer.

En primer lugar, crea nuevos directorios /var/www/.config y /var/www/.cache que serán utilizados por Composer para almacenar la caché de dependencias y la configuración. A continuación, también debes cambiar la propiedad de ambos directorios al usuario www-data.

mkdir -p /var/www/{.config,.cache}
sudo chown -R www-data /var/www/{.config,.cache}

Desplázate al directorio /var/www y descarga el código fuente de BookStack en el directorio bookstack. Tu directorio de instalación de BookStack debe ser /var/www/bookstack.

cd /var/www
git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch bookstack

Ahora cambia la propiedad del directorio /var/www/bookstack al usuario www-data y entra en él.

sudo chown -R www-data:www-data /var/www/bookstack
cd /var/www/bookstack

A continuación, copia el archivo .env.example en .env y abre el nuevo archivo utilizando el siguiente comando del editor nano.

sudo -u www-data cp .env.example .env
sudo -u www-data nano .env

Introduce el nombre de tu dominio en la opción APP_URL e introduce los datos de tu base de datos MariaDB en la opción DB_.

# The application URL
APP_URL=http://bookstack.hwdomain.io
# Database values also need to be modified
# If you follow previous command, you only need to add your DB_PASSWORD
DB_DATABASE=bookstack
DB_USERNAME=bookstack
DB_PASSWORD=p4ssword

Guarda y cierra el archivo cuando hayas terminado.

A continuación, ejecuta el siguiente comando para instalar las dependencias de PHP a través de Composer.

sudo -u www-data composer install --no-dev --no-plugins

Durante la instalación, se mostrará la siguiente salida.

Una vez instaladas las dependencias de PHP, ejecuta el siguiente comando para generar la clave secreta y migrar la base de datos.

sudo -u www-data php artisan key:generate --no-interaction --force
sudo -u www-data php artisan migrate --no-interaction --force

La clave secreta del archivo .env se actualizará, y a continuación se muestra el proceso durante la migración de la base de datos.

Cuando todo haya terminado, ejecuta el siguiente comando para cambiar la propiedad de algunos directorios al usuario www-data y asegurarte de que esos directorios permiten la escritura.

sudo chown www-data:www-data -R bootstrap/cache public/uploads storage 
sudo chmod u+rw bootstrap/cache public/uploads storage

Por último, ejecuta el siguiente comando para cambiar el permiso del archivo .env a 640. Esto garantizará que sólo el usuario www-data pueda realizar cambios en el archivo.

sudo chmod -R 640 /var/www/bookstack/.env

Configuración del host virtual Apache2

En la siguiente sección, crearás una nueva configuración de host virtual Apache2 que se utilizará para ejecutar BookStack. Por tanto, debes asegurarte de que has preparado tu nombre de dominio y de que apunta a la dirección IP del servidor.

Antes de crear una configuración de host virtual, ejecuta el siguiente comando para habilitar el módulo de reescritura en Apache2.

sudo a2enmod rewrite

Ahora crea una nueva configuración de host virtual /etc/apache2/sites-available/bookstack. conf utilizando el siguiente comando del editor nano.

sudo nano /etc/apache2/sites-available/bookstack.conf

Inserta la siguiente configuración y asegúrate de cambiar el nombre de dominio dentro de la opción ServerName. En el siguiente ejemplo se utilizará el dominio bookstack.hwdomain.io para la instalación de BookStack.

<VirtualHost *:80>
    ServerName bookstack.hwdomain.io
    ServerAdmin webmaster@localhost
    DocumentRoot /var/www/bookstack/public/
<Directory /var/www/bookstack/public/>
Options Indexes FollowSymLinks
AllowOverride None
Require all granted
<IfModule mod_rewrite.c>
<IfModule mod_negotiation.c>
Options -MultiViews -Indexes
</IfModule>
RewriteEngine On
# Handle Authorization Header
RewriteCond %{HTTP:Authorization} .
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
# Redirect Trailing Slashes If Not A Folder...
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_URI} (.+)/$
RewriteRule ^ %1 [L,R=301]
# Handle Front Controller...
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]
</IfModule>
</Directory>

ErrorLog ${APACHE_LOG_DIR}/bookstack-error.log
CustomLog ${APACHE_LOG_DIR}/bookstack-access.log combined
</VirtualHost>

Guarda y cierra el archivo cuando hayas terminado.

A continuación, ejecuta el siguiente comando para activar el archivo de host virtual bookstack.conf y verifica tu sintaxis de Apache2.

sudo a2ensite bookstack.conf
sudo apachectl configtest

Si utilizas la sintaxis adecuada, se imprimirá la salida«Sintaxis OK» en tu terminal.

Por último, ejecuta el siguiente comando systemctl para reiniciar el servicio aapche2 y aplicar los cambios que has realizado.

sudo systemctl restart apache2

Proteger Bookstack con certificados SSL/TLS

En esta guía, asegurarás BookStack con certificados SSL/TLS, que se pueden generar desde Letsencrypt mediante la herramienta Certbot.

Instala Certbot y el plugin Certbot para Apache mediante el comando apt install que aparece a continuación. Escribe y para confirmar y continuar con la instalación.

sudo apt install certbot python3-certbot-apache

Ahora ejecuta el siguiente comando certbot para generar certificados SSL/TLS y asegurar tu instalación de BookStack. Asegúrate de cambiar el nombre de dominio y la dirección de correo electrónico en el siguiente comando.

sudo certbot --apache --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d bookstack.hwdomain.io

Una vez finalizado el proceso, tus certificados SSL/TLS estarán disponibles en el directorio /etc/letsencrypt/live/bookstack.hwdomain.io. Además, tu instalación de BookStack se configurará automáticamente con HTTPS, que se configura a través del plugin de Apache Certbot.

Acceder a Bookstack

Llegados a este punto, todo está configurado y tu instalación de BookStack ha finalizado. Ahora puedes acceder a tu instalación de BookStack.

Inicia tu navegador web y visita el nombre de dominio de tu instalación de BookStack, como https://bookstack.hwdomain.io/, y serás redirigido a la página de inicio de sesión de BookStack.

Introduce la dirección de correo electrónico por defecto [email protected] y la contraseña es password, después haz clic en Iniciar sesión.

Si tienes éxito, deberías ver el panel de BookStack como el siguiente:

Conclusión

Para terminar, has instalado con éxito BookStack en un servidor Debian 12 paso a paso. Has instalado BookStack mediante Git, Composer y con paquetes LAMP Stack (Apache2, MariaDB y PHP). También has asegurado BookStack con certificados SSL/TLS de Letsencrypt. A partir de aquí, ya puedes rellenar tu información y construir tu propia documentación.