Configuration

A Webmachine instance configuration is comprised of a list of erlang tuples. This syntax may seem strange to those not familiar with Erlang, but it is relatively simple and the following information should help.

Configuration Options

IP address and port number

The Webmachine instance accepts connections on the IP address specified by the ip tuple in the configuration and listens on the port number specified by the port tuple. The IP address should be a string and the port number must be a valid integer.

{ip, "192.168.1.1"},
{port, 8080},

SSL

SSL can be enabled for a Webmachine instance by including an ssl tuple in the configuration. The configuration should specify a certfile and a keyfile to be be used. The optional cacertfile can be specified to enable clients to validate the server certificate.

{ssl, true},
{ssl_opts, [
               {certfile, "/etc/ssl/cert.pem"},
               {keyfile, "/etc/ssl/key.pem"},
               {cacertfile, "/etc/ssl/ca_certs.pem"}
           ]}

Socket options

There are some optional options that may be specified in the configuration that are passed through to the web server to set certain socket options.

To change the default size of the queue of pending connections, the backlog option may be set. The default value is 128.

{backlog, 256},

The nodelay option may also be specified. If this option is set to true then the TCP_NODELAY option is turned on for the socket. The default is false.

{nodelay, true},

Dispatch groups

As of 1.10.0 it is possible to create dispatch groups in order to run multiple instances of mochiweb within a single Webmachine application. Each dispatch group has a separate configuration and a distinct set of dispatch rules. Each group must have a distinct name that is used to map to its set of dispatch rules. This name is specified by dispatch_group in the configuration.

e.g.

{dispatch_group, public_interface},

More information on dispatch rules is available here.

Error handler

Webmachine includes a default error handler module, webmachine_error_handler, but users may also implement their own. An error handler must implement the render_error/3 function. webmachine_error_handler.erl can serve as a useful guide for users wanting to implement a custom error handler.

To enable a custom error handler specify the module as the value for the error_handler key in the configuration.

{error_handler, my_error_handler_mod},

URL rewriting

As of 1.10.0, Webmachine features the ability to rewrite incoming URLs and headers based on a set of rules. These rules can be defined in an Erlang module and the module name specified as part of the configuration. More details about it can be found here.

The rules module can be specified in the configuration as follows:

{rewrite_module, my_rewrite_rules_mod},

Resource module option

When logging, Webmachine uses the value of the resource_module metadata to indicate which resource the log output pertains to. The value is normally the module associated with the dispatch rule for the resource. This option allows the value of that metadata to be set instead to the value of a two-tuple specified in the ModOpts list of the dispatch rule.

For example, take the case where the Webmachine resource modules duplicate a lot of code in implementing the required callbacks to service requests. In order to reduce code duplication much of the common code is consolidated in a single module and that common module is specified as the resource module in all dispatch rules. This would normally cause all log output to appear to come from a single module. To avoid this, the ModOpts for each dispatch rule includes a submodule entry whose value is the module that implements the resource specialization code and the following option is included in the Webmachine configuration:

{resource_module_option, submodule},

Creating the supervisor spec

Once the desired configuration options have been selected, the next step is to create a child spec to give to an erlang supervisor process. An example would be:

{wm_instance_1,
    {webmachine_mochiweb, start, [Config]},
        permanent, 5000, worker, dynamic}.

wm_instance_1 serves as an identifier used by the erlang supervisor process. It may be changed. If using more than once instance of webmachine in an application, each instance must use a unique identifier.