wiki:FactoryManual/StandardFactory

Version 2 (modified by sander, 8 years ago) (diff)

--

Factory Manual: Using the standard factory

<< Previous: Setting up your account | Next: Creating new backends >>

This chapter details the installation and configuration of the standard factory that is distributed by Officeshots.org. If you are implementing your own factory from scratch you can skip this chapter, but if you want to develop a factory builds on the standard factory then you want to read this so you understand how configuration works.

Downloading and installing the standard factory

You can download the standard factory from our Subversion repository at http://code.officeshots.org/officeshots. You can also download a tar.gz package but it is easier to keep up-to-date when you download it from Subversion. Use the following command to download the latest version of the factory from Subversion:

$> svn checkout http://code.officeshots.org/officeshots/trunk/factory

To update your factory to the latest version, go to the directory where the factory is and run:

$> svn update

Next, copy conf/config.default.ini to conf/config.ini and open it in a text editor. Change the settings in the global section according to your preferences.

factory_name
The name of your factory. This must match the name of the factory that you created on the website. You can pick any name you like but all your factories must have a different name.
transport
Which SSL transport you want to use. Not all transports work on all platforms. Currently supported are m2crypto which requires the Python M2Crypto library, and pyssl which uses Python's built-in HTTPS connection. The default is currently mycrypto because it allows the use of PEM encrypted SSL client certificates.
log_file
The logfile that you want to log to.

By default log_file is set to /var/log/officeshots.org. On most Unix/Linux? systems you are not allowed to write to this directory with your normal account. You are strongly suggested to change this parameter.

log_level
Determines the verbosity of the log. Can be set to one of debug, info, warning, error or critical.
log_format
Determines the format of the log entries. Please see the Python documentation on logging for more detail.
xmlrpc_endpoint
The XML-RPC endpoint. This should normally be https://www.officeshots.org/xmlrpc
tls_certificate_file
A full path pointing to the file containing your PEM-encoded SSL/TLS certificate.
tls_key_file
Full path pointing to the file containing your PEM-encoded SSL/TLS private key. This can be the same file as your certificate.
load_max
The maximum system load. If the system load is greater than this value then the factory will sleep instead of poll for new jobs. This has currently no effect on Windows.
tmp_files
Path to a directory that will be used to store temporary files.
backends
A comma separated list of backends (applications) that are enabled. For every worker that you added to your factory on the server you should have a backend in your configuration file. See below for more information about backends.

Configuring backends

For every worker that you added to your factory on the Officeshots website you should have a backend in your configuration file. You can name the backends any way you like. Add them all to the backends in a comma separated list. Then, for all the backends in that list you need to have a separate configuration section. For example, if you added AbiWord? and Gnumeric as workers on the Officeshots website then you need two backends in your configuration file.

Example configuration

[Global]
backends = my_abiword, some_old_gnumeric

[my_abiword]
# Configuration options for AbiWord

[some_old_gnumeric]
# Configuration options for Gnumeric

If you do not want to use certain backends/sections then you only need to remove them from the backends line. You do not need to remove the entire sections. All the backends have at least a few configuration options in common.

If you do not want to use certain backends/sections then you only need to remove them from the backends line. You do not need to remove the entire sections. All the backends have at least a few configuration options in common.

application
The name of the application. This must be the same as the application name configured on the website.
version
The version number of the application, such as "3.0" or "2003 SP2".
doctypes
A comma separated list of doctypes codes that the application can handle, such as odt, ods or odp. This must be a subset of the doctypes that the application can handle according to the server. For example, OfficeReader? can handle odt, ods and odp files. You can skip processing of presentations by configuring the backend to only accept odt and ods files.

These are document type codes

formats
A comma separated list of format codes that the application can process such as png, pdf or odf.
backend
The name of the Python backend class that implements the worker. See the next section on which backends are available.

Besides these standard configuration options each backend can have extra configuration options depending on the backend type.

OOOServer

The OOOServer backends implements OpenOffice.org running in headless mode. As such it is not able to produce screenshots but only ODF roundtrip and PDF export. To use the OOOServer backend you must have OpenOffice.org running in headless mode. See Running OpenOffice.org in headless mode.

Besides the standard configuration options, you can set the following options for the OOOServer backend.

ooo_host
The hostname of the machine that OpenOffice.org is running on in headless mode. Normally this should be localhost. If you set this option then you should also set the ooo_port option.
ooo_port
The port number that OpenOffice.org is listening to. This should normally be 8100.
ooo_pipe
The name of the pipe that OpenOffice.org is listening to. If you set this option then you should not set the ooo_host and ooo_port options.

On Windows XP and Vista it is not possible to connect to OpenOffice.org using a socket with the ooo_host and ooo_port options. You should use a pipe instead.

Running OpenOffice.org in headless mode

When OpenOffice.org is running in headless mode you cannot start it yourself anymore. The easiest thing to do is to create a new user on your computer and run OpenOffice.org in headless mode under that user account instead of your own. Linux users can start OpenOffice.org in headless mode using the following command:

$> soffice -headless -nologo -norestore -accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager

For Windows users there is a simple batch file in the utils directory called utils/oooserver.bat. Simply edit that file, make sure that the OOOPATH is correct and that the OOOPIPE is the same as the pipe name in your configuration file. Then double-click the file to start OpenOffice.org in headless mode. If you want to start OpenOffice.org manually on Windows then you can execute the following command:

$> soffice.exe -headless -nologo -norestore "-accept=pipe,name=officeshots;urp;StarOffice.ServiceManager"

Sometimes OpenOffice.org on Windows does not install the Python UNO bridge. You can re-install OpenOffice.org. Make sure you choose Custom install amd check the box that installs Python UNO.

The oooserver init script in the utils directory can be used to automatically start and stop OpenOffice.org in headless mode on a Debian or Ubuntu machine. It uses xvbf, the X Virtual FrameBuffer so it can even run on a machine that has no complete X Server installed such as most servers. Place this file in your /etc/init.d directory and make it executable. Then you need to add symlinks to it in the appropriate places. You can execute the following command (as root) to create these symlinks automatically:

#> update-rc.d oooserver defaults

You will also need to configure the oooserver init script. By default oooserver will run as user nobody but on many systems this user does not have a valid home directory. OpenOffice.org does not start without a valid home directory. Either make sure user nobody exists and has a valid home directory, or change the USER parameter in the oooserver init script.

CLI

<< Previous: Setting up your account | Next: Creating new backends >>