[bug#59845] [PATCH v2 4/4] doc: Add Integrated Library System section.

[Yarl Baudig]

doc/guix.texi (System Configuration, Services): Add Integrated Library System 
Services section.
doc/guix.texi (System Configuration, Services, Integrated Library System 
Services): Add PMB.
---
 doc/guix.texi | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index a79b777826..60f0072409 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -109,6 +109,7 @@ Copyright @copyright{} 2022 Reily Siegel@*
 Copyright @copyright{} 2022 Simon Streit@*
 Copyright @copyright{} 2022 (@*
 Copyright @copyright{} 2022 John Kehayias@*
+Copyright @copyright{} 2022 Yarl Baudig
 
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -402,6 +403,7 @@ Services
 * Guix Services::               Services relating specifically to Guix.
 * Linux Services::              Services tied to the Linux kernel.
 * Hurd Services::               Services specific for a Hurd System.
+* Integrated Library System Services::   ILS services.
 * Miscellaneous Services::      Other services.
 
 Defining Services
@@ -17720,6 +17722,7 @@ declaration.
 * Guix Services::               Services relating specifically to Guix.
 * Linux Services::              Services tied to the Linux kernel.
 * Hurd Services::               Services specific for a Hurd System.
+* Integrated Library System Services::   ILS services.
 * Miscellaneous Services::      Other services.
 @end menu
 
@@ -36726,6 +36729,130 @@ An integer specifying the baud rate of the tty.
 @end table
 @end deftp
 
+@node Integrated Library System Services
+@subsection Integrated Library System Services
+
+@cindex PMB Service
+@subsubheading PMB Service
+
+@defvr {Scheme Variable} pmb-service-type
+Service type for the @uref{https://www.sigb.net/,PMB} Integrated Library 
System.
+The value for this service type is a @code{<pmb-configuration>} record.
+
+The PMB service needs a web server, @code{mariadb}/@code{mysql}, @code{php} and
+is only responsible for copying and changing ownership of files from the
+@code{pmb} package.
+@end defvr
+
+Let's start with a demonstration. Here is a sample system configuration 
(@file{pmb.scm}):
+
+@lisp
+(use-modules (gnu))
+(use-service-modules ils web networking databases)
+(use-package-modules databases)
+
+(operating-system
+  (host-name "pmb")
+  (timezone "Europe/Paris")
+  (file-systems (cons
+                 (file-system
+                   (device (file-system-label "does-not-matter"))
+                   (mount-point "/")
+                   (type "ext4"))
+                 %base-file-systems))
+  (bootloader (bootloader-configuration
+               (bootloader grub-bootloader)
+               (targets '("/dev/sdX"))))
+  (packages (cons* mariadb %base-packages))
+  (services
+   (cons* (service dhcp-client-service-type)
+          (service php-fpm-service-type
+                   (php-fpm-configuration
+                    (php-ini-file
+                     (plain-file "php.ini"
+                                 %default-pmb-php-fpm-configuration))))
+          (service nginx-service-type
+                   (nginx-configuration
+                    (server-blocks
+                     (list (nginx-server-configuration
+                            (locations
+                             (list
+                              %default-nginx-pmb-location))
+                            (listen '("localhost:8080"))
+                            (root "/srv/http/pmb")
+                            (index '("index.php")))))))
+          (service mysql-service-type
+                   (mysql-configuration
+                    (extra-content
+                     %default-pmb-mysql-configuration-extra-content)))
+          (service pmb-service-type)
+          %base-services)))
+@end lisp
+
+The interesting points are as follows.
+We import the @code{mariadb} package so that we will have access to the program
+@command{mysql}. This will be useful to set the password of the database's
+administrator. We declare a @code{php-fpm} service whose @file{php.ini} file
+is set to @code{%default-pmb-php-fpm-configuration}.
+The @code{NGinx} service is declared, with a location set to
+@code{%default-nginx-pmb-location} and a root set to @file{/srv/http/pmb}, 
which
+is the default for the @code{http-directory} field of 
@code{<pmb-configuration>}.
+The @code{mysql} service is declared with an @code{extra-content} to its 
configuration:
+@code{default-pmb-mysql-configuration-extra-content}. Finally the pmb service.
+
+Now let's run @command{guix system container -N pmb.scm} (@pxref{Invoking guix 
system}).
+Run the resulting @file{/gnu/store/...run-container}.
+Note that we want to keep the state of the database and the php files (because 
during
+the application setup (see below), the php files will be slightly modified. 
That is also why
+the PMB files need to be copied (and chowned) outside the store), we need to 
create
+two folders, say @file{/mnt/data/pmb} and @file{/mnt/data/mysql} and pass 
@option{--share}
+two times. @command{nsenter} into it to set the database's administrator 
password.
+
+@example
+# mkdir /mnt/data/mysql /mnt/data/pmb
+# /gnu/store/...run-container --share=/mnt/data/pmb=/srv/http/pmb \
+--share=/mnt/data/mysql=/var/lib/mysql
+# nsenter -a -t <replace-with-pid>
+# mysql
+> SET PASSWORD FOR 'root'@'localhost' = PASSWORD('guixisgreat');
+@end example
+
+Go to @uref{localhost:8080}. Follow the steps. Note that for the database 
server parameters,
+``localhost'' won't work, it's ``127.0.0.1'' and the user is ``root''.
+Once the installation is complete, you are redirected to the login page. The 
name is ``admin'',
+the password is ``admin''.
+
+Now lets detail fields.
+
+@defvr {Scheme Variable} %default-pmb-php-fpm-configuration
+This is meant to represent the content of @file{php.ini} for the
+@code{php-fpm} service for a recommended configuration.
+@end defvr
+
+@defvr {Scheme Variable} %default-pmb-mysql-configuration-extra-content
+Extra content to be added to @code{mariadb}/@code{mysql} configuration for 
recommended configuration.
+@end defvr
+
+@defvr {Scheme Variable} %default-nginx-pmb-location
+Location for nginx based on @code{nginx-php-location}.
+@end defvr
+
+@deftp {Data Type} pmb-configuration
+This data type represents the configuration for PMB.
+
+@table @asis
+@item @code{pmb} (default: @code{pmb})
+
+@item @code{http-directory} (default: @file{/srv/http/pmb})
+Must match a webserver's root.
+
+@item @code{php-fpm-user} (default: @code{php-fpm})
+
+@item @code{php-fpm-group} (default: @code{php-fpm})
+
+@end table
+@end deftp
+
 @node Miscellaneous Services
 @subsection Miscellaneous Services
 
-- 
2.38.1