Package: guix-patches;
Reported by: Yarl Baudig <yarl-baudig <at> mailoo.org>
Date: Mon, 5 Dec 2022 21:49:01 UTC
Severity: normal
Tags: moreinfo, patch
View this message in rfc822 format
From: Yarl Baudig <yarl-baudig <at> mailoo.org> To: 59845 <at> debbugs.gnu.org Cc: Yarl Baudig <yarl-baudig <at> mailoo.org> Subject: [bug#59845] [PATCH v2 4/4] doc: Add Integrated Library System section. Date: Fri, 9 Dec 2022 12:53:49 +0100
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
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.