InGrid is a server-based product for shared document formatting. It accepts XSL-FO documents over the network and formats them by distributing the formatting tasks among multiple formatters that may run locally or on other computers in the network. Regular users publish customized documents in high volumes and varied formats. The server is accessed via straightforward controls. The users may customize server operation for their workflow.

InGrid is a direct replacement of EnMasse. It is completely backward compatible with EnMasse, i.e. it accepts the same configuration files and supports the same working modes while providing significantly better performance.

Additionally, InGrid provides with REST API.

Computation-heavy processes, like XML transformation or rendering XSL-FO to PDF, require significant resources and take more time to complete if ran on a local machine.

The conservative approach to this problem is using multiple-core and multiple-CPU configurations with server-grade amounts of memory. This introduces the need of effective and scalable task management tools to distribute the rendering tasks between the cores, detect and retry on failures, balance the load, unify the logging, compute statistics, and so on.

While multiple-core systems may be sufficient for a certain amount of rendered documents per time unit, sooner or later, any upgrade bumps into physical limits of the architecture. A really scalable solution would require the synergy of rendering engines running on multiple computers across the network. Using multiple computers, the rendering cores can achieve a data throughput at the current level of technology permits; and the price for stock single-CPU PCs is low enough to have sufficient resources to meet any business needs.

This approach also helps reliability and fail-tolerance of the grid; when the rendering engines are constantly online, the load is evenly distributed; in case when a node is down due to hardware failure or being upgraded, the entire system still processes all requests, preserves data, however, at the cost of the degraded performance. This is a well-known but not an easy task; and to really use the synergy power of the grid computing as it is known, you must resolve this issue.

RenderX XEP is a rendering engine that creates elegantly formatted print-ready template-based documents. In many deployments, it produces hundreds of thousands of documents on demand. For example:

These are just a few examples. While XEP is based on an optimized and highly-performant code, the business needs a way to scale up the performance to be able to handle a constantly growing load.

InGrid solves this problem for you. For an end user or an application programmer, it acts as a single access point. Through a shared folder, a Web form or a network connection (locally on the LAN, or across the Internet), InGrid accepts document processing requests and sends them to one of the XEP formatting engines running locally or on several computers in the local network, then delivers formatted documents back to the user. InGrid also monitors the performance of each formatting engines, notices when they go down and are restored, and re-adjusts the distribution of the requests according to the workload. When a server fails in the midst of processing a request, InGrid re-submits the request to a different server; thus the only impact is a slightly increased response time for that particular document. This provides the reliability of the entire service needed in today's world.

InGrid is both opaque and transparent. On one hand, it provides with a single point abstraction so that there is no need to worry about the number of engines running, or about their load; InGrid dispatches requests to the most appropriate node. On the other hand, both the access point and the processing engines have standard, embedded servers. The system administrator can instantly check the status of the nodes in the grid, identify problems and take an appropriate action. An InGrid access point takes little memory overhead and processing time, it can be deployed on a busy Intranet server, or even on a consumer-grade workstation and, as long as the processing engines run on separate machines, it does not affect the performance or throughput of the grid.

For debugging purposes, audit, and performance tuning, InGrid provides a logging facility. One can adjust the verbosity of the logging, or completely turn it off. The log files are easy to read and to process by programs.

InGrid runs on a wide range of hardware and operating systems, easy to install and requires a little maintenance.

Actinia is basically a service of the Active Folder within the local file system. Once a source document appears there (e.g., the user drops a file using a normal file manager), Actinia notices it, picks it up, and sends it for formatting to one of servers in the grid. As soon as the formatting completes, Actinia then stores the formatted document in the output folder. The output folder can be the same as, or different from, the input one. This approach works when the user sends the document for processing, for example, when a different player needs the formatted document, or when the document leaves the system in another medium (for example, printed and delivered in a hard-copy form).

Toaster is a network-activated service. It monitors a network connection, accepts source styled documents (XSL-FO), and sends back the formatted documents to the user via the same connection. Unlike the Actinia case, the client always receives the result of processing in an electronic form for local print generation. This is suitable when the user requesting document processing and is both the producer of XML sources and the consumer of their formatted output.

Fairy is a SOAP/REST server which accepts source documents (XSL-FO) and sends formatted documents back via the same connection to the requestor (a client application). It can be easily tied with any application which supports SOAP, because writing SOAP and REST clients is an easy task.

Fork is basically an integrator of an arbitrary number of services listed above (Actinia, Toaster, and Fairy). Its configuration file contains a list of config files, each of which, in turn, configure corresponding InGrid instances for each list entry. Fork then starts each listed instance. Additionally, it provides a Web interface for monitoring status of all started instances. Using Fork is an alternative to manually starting multiple InGrid instances from the command console with their own config files passed as parameters.

InGrid, in Actinia, Toaster, and Fairy configurations, can apply XSL transformation to input documents. InGrid nodes recognize xml-stylesheet processing instruction with type of "text/xml" or "text/xsl" and apply the associated stylesheets to the source document. It allows to distribute both transformation and processing among the grid nodes, and fully utilize the power of the formatting framework.

For example, an installation dedicated to the formatting of DocBook documents may provide access to DocBook XSL stylesheets stored on a local server; the nodes will load and apply the stylesheets, and then format the generated XSL FO into PDF or PostScript.

InGrid runs on any operating system that has TCP sockets, and Java Virtual Machine. Since XEP also uses Java, and InGrid is usually installed with one of its worker engines, you may already have Java installed. The installer of InGrid is Java-based; it also includes setup.bat for Windows users convenience.

Installing InGrid in Toaster mode also requires a Web server able to run CGI scripts.

In order to install InGrid, launch

setup.jar

setup.bat

After the installation, InGrid requires proper configuring in order to run. This includes creation of a configuration file. Actinia mode also requires working directories to be created and properly configured (user permissions and access mode). See example conf files in etc/, they are in XML format and contain all options commented with detailed descriptions. Uncomment required options and adjust values according to your requirements. InGrid installed as Windows service uses ingrid.conf from the root installation directory. Installing InGrid as Windows service will create basic ingrid.conf based on fairy.conf.example located at etc/ directory for testing purposes, adjust it to your requirements.

InGrid installation has three types of installed content: programs and configuration files, working directories and program log.

Working directories

Actinia requires three folders for user files: input, output, and quarantine. It monitors the input folder for new work, places the formatted result into the output folder, and keeps a copy of all files not yet formatted in the quarantine folder so that if the system fails, all files are preserved and can be reprocessed. A temporary working directory, tmp is also used.

On Unix, these folders are in /var/spool/ingrid/; suggested folder names are inp/, out/, qua/, and tmp/. InGrid requires write permission to the directories. All users ^[1] who will be submitting files for formatting must have write permission to the input directory (and probably also to the output one so that they may delete the formatted files after retrieving them).

Program logs

InGrid writes detailed logs, to detect and resolve problems and tune performance. On Unix, /var/log/ingrid/ may be used to store them. The user running InGrid must have a write permission on the logs directory.

To run InGrid, you must configure it. A configuration file determines both how InGrid interacts with the outside world and how it manages XEP engines and distributes the load. While for many parameters the default values are satisfactory, some values are required to be set explicitly to describe your local environment (the network and the computer).

InGrid is packaged with a set of initial configuration files called actinia.conf.example, toaster.conf.example, fairy.conf.example, and fork.conf.example. Copying and editing example configs from ${instDir}/etc/ is the fastest and the easiest way to start.

The configuration file is in the following XML format (in Relax NG). The complete specification of InGrid configuration file follows:

config = actinia | toaster | fairy | fork
actinia = element actinia {
	actinia-folders & settings
}

toaster = element toaster {
	toaster-folders  & settings
}

fairy = element fairy {
	fairy-folders & settings
}

fork = element fork {
	fork-tines & element option {
		attribute name {"http-port"},
		attribute value {string}
	}?
}

fork-tines = element tine {
		attribute conf {string}
	}+
	
settings = options & servers & cliser

actinia-folders = element folders {
	attribute input {string},
	attribute output {string},
	attribute quarantine {string},
	attribute temporary {string}
}

toaster-folders = element folders {
	attribute temporary {string}
}

fairy-folders = element folders {
	attribute temporary {string}
}

options = element option {
	attribute name {token},
	attribute value {string}
}*

servers = servers {
	element server {
		attribute host {token}?,
		attribute port {token}?
	}+
}

cliser = element cliser {
	attribute format {token}?,
	options
}
				

The InGrid mode is set by the top-level element; it is either toaster (network server), actinia (active folder), fairy (SOAP server) or fork(proxying mode). All modes except fork require folders and servers elements.

Attributes of folders are temporary, input, output, and quarantine which specify paths to the temporary folder (InGrid kernel needs it), and, only for Actinia, to the input, output and quarantine folders. Actinia looks for XSL-FO sources in the inputfolder and writes formatted results to output folder. It keeps a copy of each XSL-FO source in the quarantine folder until the processing has finished. This allows the user to re-submit documents after a malfunction (for example, due to a power failure or a hardware problem). Both input and output attribute values can point to the same location: Actinia picks files ending with '.fo' extension by default. You can set a different input filter. See the list of options below.

Here's a sample folders section:

<folders
    temporary="'C:/InGrid/tmp'"/>

servers defines servers available to the access point. For each server, host is the server's host name or IP address ('localhost' by default), and port is the XEP engine's port (the default value is 6570). You can list the same server multiple times if you want it to load it more heavily. XEP engines are multi-threaded and handle concurrent sessions efficiently.

Here's a sample servers section:

<servers>
    <server host="'localhost'" port="6570"/>
</servers>

CLISER, RenderX XEP Client-Server protocol, is the underlying protocol layer; element cliser sets the required document format (pdf is the default value, ps (for PostScript), or xep may be used), and can contain CLISER options (see the documentation on XEP for the list of option names). Use the same names as are available for XEP and prepend core options with 'FRM:' and generator options with 'GEN:' (optionally followed by the format's name and a colon). For example, the following fragment:

<cliser format="pdf">
  <option name="FRM:VALIDATE" value="'true'"/>
  <option name="GEN:pdf:COMPRESS" value="'false'"/>
</cliser>

InGrid allows tuning its performance through a number of options. The default configuration values are fine for most applications. By changing them you can build the exact configuration you want and fine-tune the load on the grid, the throughput, and the response time. Here is the list of all available options, with their data types and default values in parentheses:

The protocol involves one request and one response. The client sends the request, in the form as follows:

RECEIVE data-size systemId

followed by a zero byte ('\0' in C), and then by the data of data-size bytes in length itself. Toaster transforms the document into PDF or PostScript and returns it: it sends

RECEIVE data-size format

If InGrid is unable to format the document, it sends

ERROR message-size None

To shutdown Toaster, send message STOP to the data port.

Fairy, as a SOAP service, provides with two methods: to format and to stop. If not otherwise specified in configuration, methods names are format and stop, respectively.

Fairy provides with a WSDL document describing the service. For example, if Fairy is running at host yourhost with the default configuration, you can get the WSDL document by sumbitting GET /fairy?WSDL HTTP request to yourhost:6577 (e.g., just by typing http://yourhost:6577/fairy?WSDL in browser's address field).

Fairy, as a SOAP service, returns one of the following status codes:

See Section 7.3 for further details on commands and their arguments.

REST API is de-facto the standard approach for modern network APIs. In recent years, SOAP has been rarely used for new projects and is often replaced with the REST API because of the simplicity of the latter. REST API works in a pretty much the same way as SOAP over the same HTTP connection, but it does not require XML wrapping and Base64 encoding for both request and response. Avoiding double encoding and wrapping results in smaller network traffic and lower CPU usage and therefore provides with better overall performance (on small documents 7-10%). Writing a client code for REST API and supporting it appears simpler and faster because it consists of sending HTTP request with a raw document data and receiving a raw formatting result without requiring any additional wrapping or encoding.

A simple HTML form example for submitting a document for formatting via the Web browser:

<html><body><div>
    <form action="http://localhost:6577/format" method="POST"
             enctype="multipart/form-data">
        <label>Document to format:</label>
        <input type="file" name="upload_file[]"/>
        <label>SystemId:</label>
        <input type="url" name="systemId[]" value=""/>
        <input type="submit" value="Submit"/>
    </form>
</div></body></html>

This example can be saved as an .html file and opened in a Web browser to submit documents (assuming that InGrid is running locally), or the form part can be integrated in any other Web site. A bit more user-friendly version of this example is included in the InGrid distribution and is accessible at /format directory.

The following API endpoints are available:

If the formatting request fails, the server will return 500 Content-Type: "text/plain" with the detailed description of the failure.

Fairy supports TLS (Transport Layer Security) that allows sending sensitive documents securely via insecure networking transport. In this case, the clients are ensured they are connecting to an authentic server.

Fairy also supports two-way TLS, limiting access to authorized clients only. In this case, it stores public keys of all authorized clients and verifies the keys on each request.

InGrid distribution contains a sample of Fairy client application. One may find it in etc\JavaClient\ within the InGrid installation directory. The application shows how to use one-way and two-way TLS with Fairy.

Fairy also acts as a load-balancer. Upon arrival, all new incoming formatting requests are internally queued. Once an Agent is available, it starts processing the first queued formatting request.

The queue length may be configured. If the limit is reached, e.g. the queue is full, and a new request arrives, it gets rejected with Error 503 Service Temporary Unavailable status code and a warning is logged. Since the queue keeps open connection sockets, the queue length is actually limited by the amount of free sockets in OS' TCP stack. Normally, this limit should not be reached, and the fact that it is being actually reached usually means that the hardware configuration is insufficient for the purpose of effective load balancing.

Fairy will accept SOAP request without the type specification for method's arguments. In this case format method's first argument will be interpreted as 'string' (and will be used without any conversion) and the second argument as 'base64Binary', but for greater compatibility it suggests the following types for arguments:

Here are examples of SOAP requests:

...
<format>
	<systemId>SYSTEMID</systemId>
	<xml>XML_DATABASE64ENCODED</xml>
</format>
...

...
<format>
	<systemId xsi:type="xsd:string">SystemId</systemId>
	<xml xsi:type="xsd:base64Binary">XML_DATA_BASE64_ENCODED</xml>
</format>
...

Example for generating certificates

openssl req -new -x509 -days 365 -nodes -out clientCert.pem \
  -keyout clientKey.pem

req - PKCS#10 certificate request and certificate generating utility.

Read full documentation at OpenSSL.org.

-x509 option outputs a self signed certificate instead of a certificate request. Otherwise the certificate request will be generated.

Certificate requests can be signed using x509 utility, download link

Example:

Sign a certificate request using the CA certificate above and add user certificate extensions:

openssl x509 -req -in req.pem -CA cacert.pem -CAkey key.pem \
  -CAcreateserial -out signedCert.pem