03/03: web: Remove the nginx-service procedure.

[Christopher Baines]

cbaines pushed a commit to branch master
in repository guix.

commit 39fc3004be008adfbdd29e38703834bfbd65fda8
Author: Christopher Baines <address@hidden>
Date:   Wed Aug 2 10:06:27 2017 +0100

    web: Remove the nginx-service procedure.
    
    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 bff0788..ff306a4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -14000,52 +14000,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.
 
address@hidden {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
address@hidden can be used to specify a list of @dfn{upstream
-blocks} to configure.  For this to work, use the default value for
address@hidden
-
-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
address@hidden/var/run/nginx/logs/error.log}, and after configuration in
address@hidden/var/log/nginx/error.log}.  The second location can be changed 
with the
address@hidden configuration option.
address@hidden {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.
 
address@hidden deffn
+A simple example configuration is given below.
 
address@hidden {Scheme Variable} nginx-service-type
-This is type for the nginx web server.
address@hidden
+(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))))))
address@hidden 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
address@hidden/var/run/nginx/logs/error.log}, and after configuration in
address@hidden/var/log/nginx/error.log}.  The second location can be changed
+with the @var{log-directory} configuration option.
+
address@hidden {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.
+
address@hidden @asis
address@hidden @code{nginx} (default: @code{nginx})
+The nginx package to use.
+
address@hidden @code{log-directory} (default: @code{"/var/log/nginx"})
+The directory to which NGinx will write log files.
+
address@hidden @code{run-directory} (default: @code{"/var/run/nginx"})
+The directory in which NGinx will create a pid file, and write temporary
+files.
+
address@hidden @code{server-list} (default: @code{'()})
+A list of @dfn{server blocks} to create in the generated configuration
+file, the elements should be of type
address@hidden<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.
address@hidden
+(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))))))
address@hidden example
+
address@hidden @code{upstream-list} (default: @code{'()})
+A list of @dfn{upstream blocks} to create in the generated configuration
+file, the elements should be of type
address@hidden<nginx-upstream-configuration>}.
+
+Configuring upstreams through the @code{upstream-list} can be useful
+when combined with @code{locations} in the
address@hidden<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.
+
address@hidden
+(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")))))))
address@hidden example
+
address@hidden @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},
address@hidden, @code{server-list} and @code{upstream-list}.  For
+proper operation, these arguments should match what is in
address@hidden 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.
+
address@hidden table
address@hidden 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 aefae5a..1827850 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?