Next: , Previous: , Up: Services   [Contents][Index] Web Services

The (gnu services web) module provides the Apache HTTP Server, the nginx web server, and also a fastcgi wrapper daemon.

Apache HTTP Server

Scheme Variable: httpd-service-type

Service type for the Apache HTTP server (httpd). The value for this service type is a https-configuration record.

A simple example configuration is given below.

(service httpd-service-type
               (server-name "")
               (document-root "/srv/http/")))))

Other services can also extend the httpd-service-type to add to the configuration.

(simple-service 'my-extra-server httpd-service-type
                    (list (string-append
                           "ServerName "
                            DocumentRoot \"/srv/http/\"")))))

The details for the httpd-configuration, httpd-module, httpd-config-file and httpd-virtualhost record types are given below.

Data Type: httpd-configuration

This data type represents the configuration for the httpd service.

package (default: httpd)

The httpd package to use.

pid-file (default: "/var/run/httpd")

The pid file used by the shepherd-service.

config (default: (httpd-config-file))

The configuration file to use with the httpd service. The default value is a httpd-config-file record, but this can also be a different G-expression that generates a file, for example a plain-file. A file outside of the store can also be specified through a string.

Data Type: httpd-module

This data type represents a module for the httpd service.


The name of the module.


The file for the module. This can be relative to the httpd package being used, the absolute location of a file, or a G-expression for a file within the store, for example (file-append mod-wsgi "/modules/").

Data Type: httpd-config-file

This data type represents a configuration file for the httpd service.

modules (default: %default-httpd-modules)

The modules to load. Additional modules can be added here, or loaded by additional configuration.

server-root (default: httpd)

The ServerRoot in the configuration file, defaults to the httpd package. Directives including Include and LoadModule are taken as relative to the server root.

server-name (default: #f)

The ServerName in the configuration file, used to specify the request scheme, hostname and port that the server uses to identify itself.

This doesn’t need to be set in the server config, and can be specifyed in virtual hosts. The default is #f to not specify a ServerName.

document-root (default: "/srv/http")

The DocumentRoot from which files will be served.

listen (default: '("80"))

The list of values for the Listen directives in the config file. The value should be a list of strings, when each string can specify the port number to listen on, and optionally the IP address and protocol to use.

pid-file (default: "/var/run/httpd")

The PidFile to use. This should match the pid-file set in the httpd-configuration so that the Shepherd service is configured correctly.

error-log (default: "/var/log/httpd/error_log")

The ErrorLog to which the server will log errors.

user (default: "httpd")

The User which the server will answer requests as.

group (default: "httpd")

The Group which the server will answer requests as.

extra-config (default: (list "TypesConfig etc/httpd/mime.types"))

A flat list of strings and G-expressions which will be added to the end of the configuration file.

Any values which the service is extended with will be appended to this list.

Data Type: httpd-virtualhost

This data type represents a virtualhost configuration block for the httpd service.

These should be added to the extra-config for the httpd-service.

(simple-service 'my-extra-server httpd-service-type
                    (list (string-append
                           "ServerName "
                            DocumentRoot \"/srv/http/\"")))))

The addresses and ports for the VirtualHost directive.


The contents of the VirtualHost directive, this should be a list of strings and G-expressions.


Scheme Variable: nginx-service-type

Service type for the NGinx web server. The value for this service type is a <nginx-configuration> record.

A simple example configuration is given below.

(service nginx-service-type
             (list (nginx-server-configuration
                     (server-name '(""))
                     (root "/srv/http/"))))))

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:

(simple-service 'my-extra-server nginx-service-type
                (list (nginx-server-configuration
                        (root "/srv/http/extra-website")
                        (try-files (list "$uri" "$uri/index.html")))))

At startup, 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 /var/run/nginx/logs/error.log, and after configuration in /var/log/nginx/error.log. The second location can be changed with the log-directory configuration option.

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.

nginx (default: nginx)

The nginx package to use.

log-directory (default: "/var/log/nginx")

The directory to which NGinx will write log files.

run-directory (default: "/var/run/nginx")

The directory in which NGinx will create a pid file, and write temporary files.

server-blocks (default: '())

A list of server blocks to create in the generated configuration file, the elements should be of type <nginx-server-configuration>.

The following example would setup NGinx to serve from the /srv/http/ directory, without using HTTPS.

(service nginx-service-type
             (list (nginx-server-configuration
                     (server-name '(""))
                     (root "/srv/http/"))))))
upstream-blocks (default: '())

A list of upstream blocks to create in the generated configuration file, the elements should be of type <nginx-upstream-configuration>.

Configuring upstreams through the upstream-blocks can be useful when combined with locations in the <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.

      (list (nginx-server-configuration
              (server-name '(""))
              (root "/srv/http/")
                  (uri "/path1")
                  (body '("proxy_pass http://server-proxy;"))))))))
      (list (nginx-upstream-configuration
              (name "server-proxy")
              (servers (list ""
file (default: #f)

If a configuration file is provided, this will be used, rather than generating a configuration file from the provided log-directory, run-directory, server-blocks and upstream-blocks. For proper operation, these arguments should match what is in 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.

server-names-hash-bucket-size (default: #f)

Bucket size for the server names hash tables, defaults to #f to use the size of the processors cache line.

server-names-hash-bucket-max-size (default: #f)

Maximum bucket size for the server names hash tables.

extra-content (default: "")

Extra content for the http block. Should be string or a string valued G-expression.

Data Type: nginx-server-configuration

Data type representing the configuration of an nginx server block. This type has the following parameters:

listen (default: '("80" "443 ssl"))

Each listen directive sets the address and port for IP, or the path for a UNIX-domain socket on which the server will accept requests. Both address and port, or only address or only port can be specified. An address may also be a hostname, for example:

'("" "" "8000" "*:8000" "localhost:8000")
server-name (default: (list 'default))

A list of server names this server represents. 'default represents the default server for connections matching no other server.

root (default: "/srv/http")

Root of the website nginx will serve.

locations (default: '())

A list of nginx-location-configuration or nginx-named-location-configuration records to use within this server block.

index (default: (list "index.html"))

Index files to look for when clients ask for a directory. If it cannot be found, Nginx will send the list of files in the directory.

try-files (default: '())

A list of files whose existence is checked in the specified order. nginx will use the first file it finds to process the request.

ssl-certificate (default: #f)

Where to find the certificate for secure connections. Set it to #f if you don’t have a certificate or you don’t want to use HTTPS.

ssl-certificate-key (default: #f)

Where to find the private key for secure connections. Set it to #f if you don’t have a key or you don’t want to use HTTPS.

server-tokens? (default: #f)

Whether the server should add its configuration to response.

raw-content (default: '())

A list of raw lines added to the server block.

Data Type: nginx-upstream-configuration

Data type representing the configuration of an nginx upstream block. This type has the following parameters:


Name for this group of servers.


Specify the addresses of the servers in the group. The address can be specified as a IP address (e.g. ‘’), domain name (e.g. ‘’) or a path to a UNIX socket using the prefix ‘unix:’. For addresses using an IP address or domain name, the default port is 80, and a different port can be specified explicitly.

Data Type: nginx-location-configuration

Data type representing the configuration of an nginx location block. This type has the following parameters:


URI which this location block matches.


Body of the location block, specified as a list of strings. This can contain many configuration directives. For example, to pass requests to a upstream server group defined using an nginx-upstream-configuration block, the following directive would be specified in the body ‘(list "proxy_pass http://upstream-name;")’.

Data Type: nginx-named-location-configuration

Data type representing the configuration of an nginx named location block. Named location blocks are used for request redirection, and not used for regular request processing. This type has the following parameters:


Name to identify this location block.


See nginx-location-configuration body, as the body for named location blocks can be used in a similar way to the nginx-location-configuration body. One restriction is that the body of a named location block cannot contain location blocks.

FastCGI is an interface between the front-end and the back-end of a web service. It is a somewhat legacy facility; new web services should generally just talk HTTP between the front-end and the back-end. However there are a number of back-end services such as PHP or the optimized HTTP Git repository access that use FastCGI, so we have support for it in Guix.

To use FastCGI, you configure the front-end web server (e.g., nginx) to dispatch some subset of its requests to the fastcgi backend, which listens on a local TCP or UNIX socket. There is an intermediary fcgiwrap program that sits between the actual backend process and the web server. The front-end indicates which backend program to run, passing that information to the fcgiwrap process.

Scheme Variable: fcgiwrap-service-type

A service type for the fcgiwrap FastCGI proxy.

Data Type: fcgiwrap-configuration

Data type representing the configuration of the fcgiwrap serice. This type has the following parameters:

package (default: fcgiwrap)

The fcgiwrap package to use.

socket (default: tcp:

The socket on which the fcgiwrap process should listen, as a string. Valid socket values include unix:/path/to/unix/socket, and tcp6:[ipv6_addr]:port.

user (default: fcgiwrap)
group (default: fcgiwrap)

The user and group names, as strings, under which to run the fcgiwrap process. The fastcgi service will ensure that if the user asks for the specific user or group names fcgiwrap that the corresponding user and/or group is present on the system.

It is possible to configure a FastCGI-backed web service to pass HTTP authentication information from the front-end to the back-end, and to allow fcgiwrap to run the back-end process as a corresponding local user. To enable this capability on the back-end., run fcgiwrap as the root user and group. Note that this capability also has to be configured on the front-end as well.

PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation with some additional features useful for sites of any size.

These features include:

... and much more.

Scheme Variable: php-fpm-service-type

A Service type for php-fpm.

Data Type: php-fpm-configuration

Data Type for php-fpm service configuration.

php (default: php)

The php package to use.

socket (default: (string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock"))

The address on which to accept FastCGI requests. Valid syntaxes are:


Listen on a TCP socket to a specific address on a specific port.


Listen on a TCP socket to all addresses on a specific port.


Listen on a unix socket.

user (default: php-fpm)

User who will own the php worker processes.

group (default: php-fpm)

Group of the worker processes.

socket-user (default: php-fpm)

User who can speak to the php-fpm socket.

socket-group (default: php-fpm)

Group that can speak to the php-fpm socket.

pid-file (default: (string-append "/var/run/php" (version-major (package-version php)) ""))

The process id of the php-fpm process is written to this file once the service has started.

log-file (default: (string-append "/var/log/php" (version-major (package-version php)) "-fpm.log"))

Log for the php-fpm master process.

process-manager (default: (php-fpm-dynamic-process-manager-configuration))

Detailed settings for the php-fpm process manager. Must be either:

display-errors (default #f)

Determines whether php errors and warning should be sent to clients and displayed in their browsers. This is useful for local php development, but a security risk for public sites, as error messages can reveal passwords and personal data.

workers-logfile (default (string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log"))

This file will log the stderr outputs of php worker processes. Can be set to #f to disable logging.

file (default #f)

An optional override of the whole configuration. You can use the mixed-text-file function or an absolute filepath for it.

Data type: php-fpm-dynamic-process-manager-configuration

Data Type for the dynamic php-fpm process manager. With the dynamic process manager, spare worker processes are kept around based on it’s configured limits.

max-children (default: 5)

Maximum of worker processes.

start-servers (default: 2)

How many worker processes should be started on start-up.

min-spare-servers (default: 1)

How many spare worker processes should be kept around at minimum.

max-spare-servers (default: 3)

How many spare worker processes should be kept around at maximum.

Data type: php-fpm-static-process-manager-configuration

Data Type for the static php-fpm process manager. With the static process manager, an unchanging number of worker processes are created.

max-children (default: 5)

Maximum of worker processes.

Data type: php-fpm-on-demand-process-manager-configuration

Data Type for the on-demand php-fpm process manager. With the on-demand process manager, worker processes are only created as requests arrive.

max-children (default: 5)

Maximum of worker processes.

process-idle-timeout (default: 10)

The time in seconds after which a process with no requests is killed.

Scheme Procedure: nginx-php-fpm-location [#:nginx-package nginx] [socket (string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")]

A helper function to quickly add php to an nginx-server-configuration.

A simple services setup for nginx with php can look like this:

(services (cons* (dhcp-client-service)
                 (service php-fpm-service-type)
                 (service nginx-service-type
                           (server-name '(""))
                           (root "/srv/http/")
                            (list (nginx-php-location)))
                           (https-port #f)
                           (ssl-certificate #f)
                           (ssl-certificate-key #f)))

The cat avatar generator is a simple service to demonstrate the use of php-fpm in Nginx. It is used to generate cat avatar from a seed, for instance the hash of a user’s email address.

Scheme Procedure: cat-avatar-generator-serice [#:cache-dir "/var/cache/cat-avatar-generator"] [#:package cat-avatar-generator] [#:configuration (nginx-server-configuration)]

Returns an nginx-server-configuration that inherits configuration. It extends the nginx configuration to add a server block that serves package, a version of cat-avatar-generator. During execution, cat-avatar-generator will be able to use cache-dir as its cache directory.

A simple setup for cat-avatar-generator can look like this:

(services (cons* (cat-avatar-generator-service
                    (server-name '(""))))


The program is a customizable web interface to browse Guix packages, initially designed for users of high-performance computing (HPC) clusters.

Scheme Variable: hpcguix-web-service-type

The service type for hpcguix-web.

Data Type: hpcguix-web-configuration

Data type for the hpcguix-web service configuration.


A gexp (see G-Expressions) specifying the hpcguix-web service configuration. The main items available in this spec are:

title-prefix (default: "hpcguix | ")

The page title prefix.

guix-command (default: "guix")

The guix command.

package-filter-proc (default: (const #t))

A procedure specifying how to filter packages that are displayed.

package-page-extension-proc (default: (const '()))

Extension package for hpcguix-web.

menu (default: '())

Additional entry in page menu.

See the hpcguix-web repository for a complete example.

package (default: hpcguix-web)

The hpcguix-web package to use.

A typical hpcguix-web service declaration looks like this:

(service hpcguix-web-service-type
           #~(define site-config
                (title-prefix "Guix-HPC - ")
                (menu '(("/about" "ABOUT"))))))))

Next: , Previous: , Up: Services   [Contents][Index]