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.
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.
The following changes are required in Apache configuration file httpd.conf
to set up the FastCGI protocol as used by Prosper:
LoadModule fastcgi_module modules/mod_fastcgi.so
The directive loads the mod_fastcgi module. On Windows, the module
library might have extension dll rather than so.
FastCgiExternalServer virtual_path -host host_name:port -idle-timeout 5 -flush
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.
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.
FastCgiIpcDir pipe_root FastCgiExternalServer virtual_path -socket pipe_name -idle-timeout 5 -flush
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.
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.
LoadModule rewrite_module modules/mod_rewrite.so RewriteEngine on
Loads the mod_rewrite module and enables URL rewriting.
RewriteRule ^/(.*)\.psp$ virtual_path/$1\.xhtml [last]
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.
RewriteRule ^/(.*)\.psp$ /ProsperPages/$1\.xhtml [last]
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.