Installation and configuration

This section describes the steps to be taken to set up Prolog Server Pages Extensible Architecture. Prosper requires a FastCGI-compliant web server for operation. While it is compatible to any FastCGI implementation, the steps below elaborate how to install Prosper with Apache series 2 web server only. Web servers of different vendors require slightly but not conceptually different steps to put Prosper into action.

In order to configure Prosper, two distinct steps have to be carried out. First, Prosper should be configured to establish a connection with the web server so that it can listen to requests. This is done by means of the mod_fastcgi module in Apache. Second, the web server should be configured to forward certain request types to Prosper, in particular, processing PSP documents. This latter is performed by means of mod_rewrite via URL rewriting.

Prosper operates as an external server in mod_fastcgi terminology. In other words, it listens to incoming connections on a dedicated port or pipe, depending on configuration. It is the role of mod_fastcgi, integrated with the web server, to connect to the external server, transmitting requests to Prosper, which in turn generates the reply and forwards it back to mod_fastcgi. As the web server process and the external server process are independent, the architecture is resilient against failures.

FastCGI external server architecture 

In addition, it is desirable that only server pages (PSP documents) be processed by Prosper and other document types such as images or other multimedia content be served directly by the web server. For this end, a URL rewriting mechanism should be configured which maps URLs that target Prosper to a special virtual URL associated with the FastCGI external server, leaving regular URLs intact. Hence, regular URLs will correspond to entries in the filesystem, while requests to PSP documents will be transformed so that they are served by Prosper rather than the web server. The distinction is made based on the extension of the requested document. Documents with extension psp are captured by mod_rewrite and automatically forwarded to Prosper via mod_fastcgi.

Configuring FastCGI

The following changes are required in Apache configuration file httpd.conf to set up the FastCGI protocol as used by Prosper:

Syntax

LoadModule fastcgi_module modules/mod_fastcgi.so

Semantics

The directive loads the mod_fastcgi module. On Windows, the module library might have extension dll rather than so.

Configuring FastCGI with TCP/IP

Syntax

FastCgiExternalServer virtual_path -host host_name:port -idle-timeout 5 -flush

Semantics

The directive registers all requests that map to an entry below virtual_path in hierarchy to be handled by the external server process (i.e. Prosper). For such entries, mod_fastcgi connects to the specified port on host_name transmitting all data associated with the HTTP request via FastCGI. The virtual path does not have to correspond to an actual filesystem entry but should be located within the document root.

Example

FastCgiExternalServer "C:/htdocs/ProsperPages" -host localhost:1160 -idle-timeout 5 -flush

For the example to work, Prosper has to be configured with prosper_option(port, 1160). See module prosper_configuration for details.

Configuring FastCGI with named pipes

Syntax

FastCgiIpcDir pipe_root
FastCgiExternalServer virtual_path -socket pipe_name -idle-timeout 5 -flush

Semantics

The directives register all requests that map to an entry below virtual_path to be handled by the external server process (i.e. Prosper). For such entries, mod_fastcgi connects to the pipe identified by concatenating pipe_root and pipe_name transmitting all data associated with the HTTP request. The virtual path is an absolute path, which does not have to correspond to an actual filesystem entry but should be located within the document root in terms of filesystem hierarchy.

On Windows, pipe_root and pipe_name are joined by a backslash. pipe_root has the format \\host_name\pipe\pipe_identifier. As the backslash itself is a special character in Apache, it has to be doubled to be escaped.

Example

FastCgiIpcDir "\\\\.\\pipe\\Prosper"
FastCgiExternalServer "C:/htdocs/ProsperPages" -socket "FastCGI" -idle-timeout 5 -flush

For the example to work, Prosper has to be configured with prosper_option(pipe, '\\\\.\\pipe\\Prosper\\FastCGI'). See module prosper_configuration for details.

Configuring URL rewriting

Syntax

LoadModule rewrite_module modules/mod_rewrite.so
RewriteEngine on

Semantics

Loads the mod_rewrite module and enables URL rewriting.

Syntax

RewriteRule ^/(.*)\.psp$ virtual_path/$1\.xhtml [last]

Semantics

Declares the rewriting rule for files with extension psp. Requests that match the regular expression are redirected to point to a virtual directory. The virtual directory is associated with a FastCGI external server, which eventually handles the request. This way all requests to files with extension psp are handled by Prosper, whereas regular files are unaffected, which allows embedded images or other multimedia content to be served directly by Apache rather than by the much slower Prosper. The virtual directory is to be specified relative to the server root.

This rule changes the extension from psp to xhtml. As Prosper documents validate as XML documents, this extension is more suggestive for HTML and XML editors.

Example

RewriteRule ^/(.*)\.psp$ /ProsperPages/$1\.xhtml [last]

Configuration example for Windows

First, we assume that Prosper is configured as follows:

prosper_option(module_directory, 'c:/Projects/Prosper/Implementation/Examples/Modules/').
prosper_option(document_directory, 'c:/Projects/Prosper/Implementation/Examples/ProsperPages/').

In addition, we assume that the web server root points to c:/htdocs. The Apache configuration file thus looks as follows:

#
# Prolog Server Pages Extensible Architecture:
# Apache 2 configuration
#

# Load the FastCGI and the URL rewriting modules
LoadModule fastcgi_module modules/mod_fastcgi.so
LoadModule rewrite_module modules/mod_rewrite.so

# Turn on URL rewriting
RewriteEngine on

# Declare the rewriting rule for files with extension .psp
# The virtual directory is relative to the server root.
RewriteRule ^/(.*)\.psp$ /ProsperPages/$1\.xhtml [last]

# Configure FastCGI for communication over TCP/IP
# The directory should be the same as specified in the above RewriteRule but
# should be given as an absolute filesystem path
FastCgiExternalServer "c:/htdocs/ProsperPages" -host localhost:1160

# Configure FastCGI for communication over named pipes on Windows
# FastCgiIpcDir "\\\\.\\pipe\\Prosper"
# FastCgiExternalServer "c:/htdocs/ProsperPages" -socket "FastCGI"

Prolog Server Pages is now ready to use. Launch the Prosper server and start listening for connections. Requests to files with extension .psp will be automatically redirected to the virtual path

/ProsperPages/directory/filename.xhtml

This will be mapped to the absoulte filesystem path

c:/Projects/Prosper/Implementation/Examples/ProsperPages/directory/filename.xhtml

In contrast, requests for files with a different extension ext will map to the absoulte filesystem path

c:/htdocs/directory/filename.ext

Therefore, requests served by Prosper and the web server are mixed transparently and gracefully. If using localhost, you can try http://localhost/index.psp.

SourceForge.net