Toggle diff (204 lines)
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
