[bug#28125] [PATCH] NGinx service changes (add default value, and remove nginx-service procedure)

[bug#28125] [PATCH] NGinx service changes (add default value, and remove nginx-service procedure)

[Christopher Baines]

[-- Attachment #1: Type: text/plain, Size: 380 bytes --]


Christopher Baines (3):
  web: Export more nginx related procedures, macros and record types
  web: Add default-value for the nginx-service-type
  web: Remove the nginx-service procedure.

 doc/guix.texi        | 149 +++++++++++++++++++++++++++++++++++++++------------
 gnu/services/web.scm |  56 +++++++++++-------- 
2 files changed, 150 insertions(+), 55 deletions(-)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 963 bytes --]

[bug#28125] [PATCH 1/3] web: Export more nginx related procedures, macros and record types

[Christopher Baines]

This makes it possible to work with the configuration of the NGinx service
programatically.

* gnu/services/web.scm (<nginx-configuration>, <nginx-server-configuration>,
  <nginx-upstream-configuration>, <nginx-location-configuration>,
  <nginx-named-location-configuration>): Export NGinx related record
  types.
  (nginx-configuration-*, nginx-server-configuration-*,
  nginx-upstream-configuration-*, nginx-location-configuration-*,
  nginx-named-location-configuration-*): Export NGinx related record
  procedures.
  (nginx-configuration): Export NGinx related record macro.
---
 gnu/services/web.scm | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/gnu/services/web.scm b/gnu/services/web.scm
index cc7adeb5e..4156b1a56 100644
--- a/gnu/services/web.scm
+++ b/gnu/services/web.scm
@@ -30,16 +30,47 @@
   #:use-module (guix gexp)
   #:use-module (srfi srfi-1)
   #:use-module (ice-9 match)
-  #:export (nginx-configuration
+  #:export (<nginx-configuration>
+            nginx-configuration
             nginx-configuration?
+            nginx-configuartion-nginx
+            nginx-configuration-log-directory
+            nginx-configuration-run-directory
+            nginx-configuration-server-blocks
+            nginx-configuration-upstream-blocks
+            nginx-configuration-file
+
+            <nginx-server-configuration>
             nginx-server-configuration
             nginx-server-configuration?
+            nginx-server-configuration-http-port
+            nginx-server-configuartion-https-port
+            nginx-server-configuration-server-name
+            nginx-server-configuration-root
+            nginx-server-configuration-locations
+            nginx-server-configuration-index
+            nginx-server-configuration-ssl-certificate
+            nginx-server-configuration-ssl-certificate-key
+            nginx-server-configuration-server-tokens?
+
+            <nginx-upstream-configuration>
             nginx-upstream-configuration
             nginx-upstream-configuration?
+            nginx-upstream-configuration-name
+            nginx-upstream-configuration-servers
+
+            <nginx-location-configuration>
             nginx-location-configuration
             nginx-location-configuration?
+            nginx-location-configuration-uri
+            nginx-location-configuration-body
+
+            <nginx-named-location-configuration>
             nginx-named-location-configuration
             nginx-named-location-configuration?
+            nginx-named-location-configuration-name
+            nginx-named-location-configuration-body
+
             nginx-service
             nginx-service-type
 
-- 
2.14.1

[bug#28125] [PATCH 2/3] web: Add default-value for the nginx-service-type

[Christopher Baines]

---
 gnu/services/web.scm | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/gnu/services/web.scm b/gnu/services/web.scm
index 4156b1a56..aefae5aed 100644
--- a/gnu/services/web.scm
+++ b/gnu/services/web.scm
@@ -324,7 +324,9 @@ of index files."
                             (inherit config)
                             (server-blocks
                               (append (nginx-configuration-server-blocks config)
-                              servers)))))))
+                              servers)))))
+                (default-value
+                  (nginx-configuration))))
 
 (define* (nginx-service #:key (nginx nginx)
                         (log-directory "/var/log/nginx")
-- 
2.14.1

[bug#28125] [PATCH 2/3] web: Add default-value for the nginx-service-type

[Ludovic Courtès]

Christopher Baines <mail@cbaines.net> skribis:

> ---
>  gnu/services/web.scm | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/gnu/services/web.scm b/gnu/services/web.scm
> index 4156b1a56..aefae5aed 100644
> --- a/gnu/services/web.scm
> +++ b/gnu/services/web.scm
> @@ -324,7 +324,9 @@ of index files."
>                              (inherit config)
>                              (server-blocks
>                                (append (nginx-configuration-server-blocks config)
> -                              servers)))))))
> +                              servers)))))
> +                (default-value
> +                  (nginx-configuration))))

OK with a commit log.  :-)

[bug#28125] [PATCH 3/3] web: Remove the nginx-service procedure.

[Christopher Baines]

Now that the service-type has a default value, and configuration record is
accessible.

* gnu/services/web.scm (nginx-service): Remove procedure.
* doc/guix.texi (Web Services): Update and improve NGinx documentation.
---
 doc/guix.texi        | 149 +++++++++++++++++++++++++++++++++++++++------------
 gnu/services/web.scm |  19 -------
 2 files changed, 115 insertions(+), 53 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 94277ba39..35fff0e1e 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -13933,52 +13933,133 @@ Local accounts with lower values will silently fail to authenticate.
 The @code{(gnu services web)} module provides the nginx web server and
 also a fastcgi wrapper daemon.
 
-@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
-       [#:log-directory ``/var/log/nginx''] @
-       [#:run-directory ``/var/run/nginx''] @
-       [#:server-list '()] @
-       [#:upstream-list '()] @
-       [#:config-file @code{#f}]
-
-Return a service that runs @var{nginx}, the nginx web server.
-
-The nginx daemon loads its runtime configuration from @var{config-file}.
-Log files are written to @var{log-directory} and temporary runtime data
-files are written to @var{run-directory}.  For proper operation, these
-arguments should match what is in @var{config-file} to ensure that the
-directories are created when the service is activated.
-
-As an alternative to using a @var{config-file}, @var{server-list} can be
-used to specify the list of @dfn{server blocks} required on the host and
-@var{upstream-list} can be used to specify a list of @dfn{upstream
-blocks} to configure.  For this to work, use the default value for
-@var{config-file}.
-
-At startup, @command{nginx} has not yet read its configuration file, so it
-uses a default file to log error messages.  If it fails to load its
-configuration file, that is where error messages are logged.  After the
-configuration file is loaded, the default error log file changes as per
-configuration.  In our case, startup error messages can be found in
-@file{/var/run/nginx/logs/error.log}, and after configuration in
-@file{/var/log/nginx/error.log}.  The second location can be changed with the
-@var{log-directory} configuration option.
+@deffn {Scheme Variable} nginx-service-type
+Service type for the @uref{https://nginx.org/,NGinx} web server.  The
+value for this service type is a @code{<nginx-configuration>} record.
 
-@end deffn
+A simple example configuration is given below.
 
-@deffn {Scheme Variable} nginx-service-type
-This is type for the nginx web server.
+@example
+(service nginx-service-type
+         (nginx-configuration
+           (server-list
+             (list (nginx-server-configuration
+                     (server-name '("www.example.com"))
+                     (root "/srv/http/www.example.com")
+                     (https-port #f)
+                     (ssl-certificate #f)
+                     (ssl-certificate-key #f))))))
+@end example
 
-This service can be extended to add server blocks in addition to the
-default one, as in this example:
+In addition to adding server blocks to the service configuration
+directly, this service can be extended by other services to add server
+blocks, as in this example:
 
 @example
 (simple-service 'my-extra-server nginx-service-type
                 (list (nginx-server-configuration
                         (https-port #f)
+                        (ssl-certificate #f)
+                        (ssl-certificate-key #f)
                         (root "/srv/http/extra-website"))))
 @end example
 @end deffn
 
+At startup, @command{nginx} has not yet read its configuration file, so
+it uses a default file to log error messages.  If it fails to load its
+configuration file, that is where error messages are logged.  After the
+configuration file is loaded, the default error log file changes as per
+configuration.  In our case, startup error messages can be found in
+@file{/var/run/nginx/logs/error.log}, and after configuration in
+@file{/var/log/nginx/error.log}.  The second location can be changed
+with the @var{log-directory} configuration option.
+
+@deffn {Data Type} nginx-configuration
+This data type represents the configuration for NGinx. Some
+configuration can be done through this and the other provided record
+types, or alternatively, a config file can be provided.
+
+@table @asis
+@item @code{nginx} (default: @code{nginx})
+The nginx package to use.
+
+@item @code{log-directory} (default: @code{"/var/log/nginx"})
+The directory to which NGinx will write log files.
+
+@item @code{run-directory} (default: @code{"/var/run/nginx"})
+The directory in which NGinx will create a pid file, and write temporary
+files.
+
+@item @code{server-list} (default: @code{'()})
+A list of @dfn{server blocks} to create in the generated configuration
+file, the elements should be of type
+@code{<nginx-server-configuration>}.
+
+The following example would setup NGinx to serve @code{www.example.com}
+from the @code{/srv/http/www.example.com} directory, without using
+HTTPS.
+@example
+(service nginx-service-type
+         (nginx-configuration
+           (server-list
+             (list (nginx-server-configuration
+                     (server-name '("www.example.com"))
+                     (root "/srv/http/www.example.com")
+                     (https-port #f)
+                     (ssl-certificate #f)
+                     (ssl-certificate-key #f))))))
+@end example
+
+@item @code{upstream-list} (default: @code{'()})
+A list of @dfn{upstream blocks} to create in the generated configuration
+file, the elements should be of type
+@code{<nginx-upstream-configuration>}.
+
+Configuring upstreams through the @code{upstream-list} can be useful
+when combined with @code{locations} in the
+@code{<nginx-server-configuration>} records.  The following example
+creates a server configuration with one location configuration, that
+will proxy requests to a upstream configuration, which will handle
+requests with two servers.
+
+@example
+(service
+  nginx-service-type
+  (nginx-configuration
+    (server-list
+      (list (nginx-server-configuration
+              (server-name '("www.example.com"))
+              (root "/srv/http/www.example.com")
+              (https-port #f)
+              (ssl-certificate #f)
+              (ssl-certificate-key #f)
+              (locations
+                (list
+                  (nginx-location-configuration
+                  (uri "/path1")
+                  (body '("proxy_pass http://server-proxy;"))))))))
+    (upstream-list
+      (list (nginx-upstream-configuration
+              (name "server-proxy")
+              (servers (list "server1.example.com"
+                             "server2.example.com")))))))
+@end example
+
+@item @code{config-file} (default: @code{#f})
+If the @var{config-file} is provided, this will be used, rather than
+generating a configuration file from the provided @code{log-directory},
+@code{run-directory}, @code{server-list} and @code{upstream-list}.  For
+proper operation, these arguments should match what is in
+@var{config-file} to ensure that the directories are created when the
+service is activated.
+
+This can be useful if you have an existing configuration file, or it's
+not possible to do what is required through the other parts of the
+nginx-configuration record.
+
+@end table
+@end deffn
+
 @deftp {Data Type} nginx-server-configuration
 Data type representing the configuration of an nginx server block.
 This type has the following parameters:
diff --git a/gnu/services/web.scm b/gnu/services/web.scm
index aefae5aed..18278502e 100644
--- a/gnu/services/web.scm
+++ b/gnu/services/web.scm
@@ -328,25 +328,6 @@ of index files."
                 (default-value
                   (nginx-configuration))))
 
-(define* (nginx-service #:key (nginx nginx)
-                        (log-directory "/var/log/nginx")
-                        (run-directory "/var/run/nginx")
-                        (server-list '())
-                        (upstream-list '())
-                        (config-file #f))
-  "Return a service that runs NGINX, the nginx web server.
-
-The nginx daemon loads its runtime configuration from CONFIG-FILE, stores log
-files in LOG-DIRECTORY, and stores temporary runtime files in RUN-DIRECTORY."
-  (service nginx-service-type
-           (nginx-configuration
-            (nginx nginx)
-            (log-directory log-directory)
-            (run-directory run-directory)
-            (server-blocks server-list)
-            (upstream-blocks upstream-list)
-            (file config-file))))
-
 (define-record-type* <fcgiwrap-configuration> fcgiwrap-configuration
   make-fcgiwrap-configuration
   fcgiwrap-configuration?
-- 
2.14.1

[bug#28125] [PATCH 3/3] web: Remove the nginx-service procedure.

[Ludovic Courtès]

Christopher Baines <mail@cbaines.net> skribis:

> Now that the service-type has a default value, and configuration record is
> accessible.
>
> * gnu/services/web.scm (nginx-service): Remove procedure.
> * doc/guix.texi (Web Services): Update and improve NGinx documentation.

LGTM, thank you!

Ludo’.

bug#28125: [PATCH 3/3] web: Remove the nginx-service procedure.

[Christopher Baines]

[-- Attachment #1: Type: text/plain, Size: 488 bytes --]

On Tue, 22 Aug 2017 15:05:07 +0200
ludo@gnu.org (Ludovic Courtès) wrote:

> Christopher Baines <mail@cbaines.net> skribis:
> 
> > Now that the service-type has a default value, and configuration
> > record is accessible.
> >
> > * gnu/services/web.scm (nginx-service): Remove procedure.
> > * doc/guix.texi (Web Services): Update and improve NGinx
> > documentation.  
> 
> LGTM, thank you!
> 
> Ludo’.

Thanks for your review Ludo, I've now pushed these 3 patches :)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 963 bytes --]

[bug#28125] [PATCH 1/3] web: Export more nginx related procedures, macros and record types

[Ludovic Courtès]

Christopher Baines <mail@cbaines.net> skribis:

> This makes it possible to work with the configuration of the NGinx service
> programatically.
>
> * gnu/services/web.scm (<nginx-configuration>, <nginx-server-configuration>,
>   <nginx-upstream-configuration>, <nginx-location-configuration>,
>   <nginx-named-location-configuration>): Export NGinx related record
>   types.
>   (nginx-configuration-*, nginx-server-configuration-*,
>   nginx-upstream-configuration-*, nginx-location-configuration-*,
>   nginx-named-location-configuration-*): Export NGinx related record
>   procedures.
>   (nginx-configuration): Export NGinx related record macro.

LGTM!