Staticmod

Staticmod is a module allowing to serve static pages (files).

Served files carry an ETag (weak, derived from the file's modification time and size) and a Last-Modified header. Conditional requests made with If-None-Match or If-Modified-Since are answered with 304 Not Modified when the file is unchanged (RFC 7232), saving bandwidth on revalidation.

Single byte-range requests are supported (RFC 7233): responses advertise Accept-Ranges: bytes, a Range request yields 206 Partial Content with a Content-Range header (and honours If-Range), enabling media streaming and resumable downloads.

Using as a library

To use that extension as a library for your OCaml programs, load OCamlfind package ocsigenserver.ext.staticmod, from your Dune file, and have a look at the API documentation.

Configuration file

Basics

To use that extension with Ocsigen Server's configuration file, load the extension like this:

<extension findlib-package="ocsigenserver.ext.staticmod"/>

Then configure your hosts as in this example:

<static dir="/path/to/the/local/directory" />

Note that when running Ocsigenserver as a daemon, a relative path is interpreted starting at /.

Rewriting URLs

You may also want to filter or rewrite URLs, as in this example, that allows user to have their home pages:

<static regexp="~([^/]*)(.*)" dest="/home/\1/public_html\2"/>

regexp is a regular expression using PERL syntax (PCRE).

Actually, for user's pages, it is better to do:

<static regexp="~([^/]*)(.*)" dest="$u(\1)/public_html\2"/>

$u(toto) will be replaced by the home directory for user toto.

You can also specify the option root as in

<static regexp="~([^/]*)(.*)" dest="$u(\1)/public_html\2" root="$u(\1)/public_html"/>

This will wave all symlinks checks above the directory u(\1)/public_html. This option is not permitted inside userconf files.

Catching HTTP errors

Here is an example on how to set a default error page for all 40x errors:

<static code="40." regexp=".*" dest="/your/error/page.html"/>

code is a regular expression (here matching 400, 401 etc.). regexp is optional (matches the URL path).

Note that if you want to catch errors from all sites, you need to put this configuration in a separate <site path="">at the end of your configuration file.

Max-age and Expires

Here is an example on how to set up the Cache-control: max-age and Expires HTTP headers:

<static dir="/path/to/the/local/directory" cache="2678400" />

The cache argument is given in seconds. (1 month in the example)

When the cache argument is 0 or no, the Cache-control: no-cache header is sent.

Staticmod and userconf

(version 1.2.0 and greater)

Staticmod is authorized inside userconf files, but all paths specified by dir or dest must be relative, and cannot contain "/../" or end by "/..". The relative paths are concatenated with the result of evaluating the attribute localpath of userconf.

Other options

See also module extendconfiguration for some options, like the ability to follow symlinks or to display directories. In particular, the old syntax readable="readable" is no longer available in staticmod (but can be simulated by the option listdirs of extendconfiguration).