6.4. Publish to Filesystem (p2fs) Configuration

The p2fs service writes published content to the file system so that another Web server (e.g. Apache) can serve this content without further intervention by CMS. This makes it possible to build highly scalable live servers that are not bound by factors such as database load.

Whenever content in CMS is published or unpublished, a corresponding task is scheduled with p2fs to update the file system appropriately. The com.arsdigita.cms.publishToFile.QueueManager periodically checks this queue and processes all entries in it.

An item is (re)published by requesting its live version from the editorial server through HTTP. The returned content is then scanned for links to other items (by looking for oid attributes in certain HTML tags). The links are rewritten to properly work on the targeted live server (see the destination parameter in Example 6-3). In addition to the main HTML file for an item, p2fs will also write all associated local assets of the item to the file system.

P2fs deployments require shared storage between the application server running CMS/p2fs and the Web server serving published content. One typical example is for p2fs to publish to a directory that is NFS-shared between the application server and the Web server. Then, when the application server writes new content to the file system, it will show up under the Web server. Another possible configuration is for the application server and Web server to be located on the same physical machine. Then, the Web server could simply link to the directory to which p2fs is writing content.

6.4.1. Basic Configuration

To use p2fs, you need to add a com.arsdigita.cms.publishToFile.Initializer entry to your enterprise.init. For example:

init com.arsdigita.cms.publishToFile.Initializer {
    destination = { 
      { "com.arsdigita.cms.ContentItem", 
        "data/p2fs", 
        false, 
        "/p2fs" },
      { "com.arsdigita.cms.Template", 
        "webapps/ROOT/packages/content-section/templates", 
        false, 
        "/templates" }
    };
    publishListener = "com.arsdigita.cms.publishToFile.PublishToFile";
    startupDelay = 30;
    pollDelay = 5;
    retryDelay = 120;
    blockSize = 40;
    maximumFailCount = 10;
    blockSelectMethod = "GroupByParent";
}

Example 6-3. P2fs configuration

The first parameter in Example 6-3, destination, is a list of publish destinations for content types. Each element in the destination list is a four-element list in the format:

{ "content type", "root directory", "shared storage", "url stub" }

Content type is the object type of the content type. Root directory must be a path to a writable directory, relative to the Web application root. Shared storage must be true if the root directory is shared NFS storage, false otherwise. URL stub must be the path component of the URL from which the live server will serve the directory contents.

The publishListener parameter must name a class that implements the listener class com.arsdigita.cms.publishToFile.PublishToFileListener. The listener is called whenever changes to the file system need to be made. It is strongly recommended that the listener in fact be a subclass of com.arsdigita.cms.publishToFile.PublishToFile, since most of the basic p2fs functionality is provided by this class.

The remaining parameters control processing of the queue of items needing to be written to the file system. Queue processing will start startupDelay seconds after the server start-up, and the queue will be polled for new entries every pollDelay seconds.

NoteNote
 

If startupDelay is set to 0, queue processing is completely disabled.

The queue manager will process blockSize queue entries within one database transaction. Setting this parameter to a higher value can speed up the overall p2fs performance, but will also consume more memory during processing.

If processing a queue entry fails for any reason, the processing is retried after retryDelay seconds. Entries that could not successfully be processed after maximumFailCount will remain in the queue, but will be ignored. Processing an entry can fail for a variety of reasons, for example because the target file system is full, or because the content could not be retrieved from the editorial server through an HTTP request. The server log will contain more detailed information about all processing failures.

The blockSelectMethod must always be set to GroupByParent.

6.4.2. Multi-JVM Deployment

If CMS is run on multiple JVMs, meaning multiple application servers, the queue processor must be disabled on all but one of these servers by setting startupDelay to 0. It is not possible to have several servers process the queue at the same time.

6.4.3. Enabling Templates for p2fs

P2fs scans all content for the HTML tags <a>, <img>, and <link>. Any such tags that contain an oid attribute will be rewritten by p2fs and adjusted for the configured publishing destination. The oid attribute must contain the ID of the target content item. For example, the fragment

<a oid="425">Another Item</a>

will be rewritten by p2fs so that the HTML link points to the correct file on the destination live server for the content item with ID 425.

P2fs uses the ContentType HTTP header it received when it requested the live item to determine the file extension of the main file written for an item. Currently, the following content types are supported:

Content TypeFile Extension
text/html.html
text/plain.txt
application/php.php
application/xml.xml
other.html

Table 6-1. P2fs Supported Content Types