Subject: Re: bug#59845: [PATCH 0/4] Add PMB (Integrated Library System)

From: Ludovic Courtès <[email-masked]>
Date: Tue, 20 Dec 2022 16:13:13 +0100

Yarl Baudig <[email-masked]> skribis:

> doc/guix.texi (System Configuration, Services): Add Integrated Library System Services section.
> doc/guix.texi (System Configuration, Services, Integrated Library System Services): Add PMB.

Neat!  Note that this should go in the same commit that adds the
service.

Likewise, we also expect system tests for each new service.  This should
also come in the same commit.  Here the system test would check that the
web server is up and running and that PMB correctly responds to basic
HTTP requests.  See ‘gnu/tests’ for example and do not hesitate to ask
on IRC if you have any questions.

> +@node Integrated Library System Services
> +@subsection Integrated Library System Services
> +
> +@cindex PMB Service
> +@subsubheading PMB Service
> +

Please add a couple of introductory sentences to give context.

> +@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")

I think we shouldn’t have to provide full OS declarations to illustrate
use of the service.  But as I wrote in a previous message, it we can
boil down configuration to (service pmb-service-type), then the example
will be much more concise.

> +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

Please leave two spaces after end-of-sentence periods (this gives a hint
to Texinfo and to Emacs).

> +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

Neat.  We should clarify that this is in case one wants to run it in a
container (there’s no obligation; one might want to run it on the bare
metal).

WDYT?

Ludo’.