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.
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 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"}
]}
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},
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.
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},
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},
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},
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.