Factory Manual: Quickstart
In August 2015 a new configure-backend.py script was added to the Officeshots factory repository. The configure-backend.py script allows you to sniff out installed office applications on your machine and setup the configuration file for you automatically. The below steps have been modified to cover the new configure-backend.py script with the longer hand configuration steps left at the end of the article for those who would prefer to perform all steps manually.
The python code has been tested in 2015 using Python version 2.7.10. A recent 2.7.x Python should be the right choice for running the code. It might work with other python versions, but that has not been tested. On OSX and Linux the factory code uses the Python M2Crypto library. On Windows the native SSL implementation from Python is used.
The initial steps such as initial account creation on officeshots and obtaining an SSL client certificate are the same for both procedures. These initial steps are not repeated:
- Register for an account on the Officeshots website, activate your account and let us know that you want to run a factory.
See Setting up your account.
- Get an SSL client certificate if you do not have one yet. See Get an SSL Certificate from CACert.
Current method continues as…
The current method which uses the configure script introduced in July 2015 the steps then continue as:
- Log in on the Officeshots website, create a new factory, give it a nice name.
- Install the office applications you would like to use on your factory. Install helper applications if needed. For instance with Apache Open Office and LibreOffice you need to ensure that you installed the Python UNO bridge with the office suite and have checked out unoconv. In addition to Python, Windows users need pywin32 installed for Word support and can find the UNO bridge when the choose Custom install when installing the application. Information specific to each application and platform is contained in the README.
- Download the latest Officeshots factory using git. While using git is the recommended method, you can also download a zip archive from the repository on gitlab. To checkout using git issue the command:
$> git clone https://gitlab.com/monkeyiq/officeshots.gitFor the rest of the document we are interested in the directory from the git repository at trunk/factory.
- Place your SSL client certificate from step 2 into a file called conf/cert.pem.
- Change directory into ./src and execute configure-backend.py to sniff out your office applications. If you have downloaded programs or compiled things your self such as WebODF then manipulate the PATH environment variable such that the tools you have installed can be found in the PATH. The sniffing run will detect the full path to each program where it might be needed and use that full path in the configuration file. So you do not need to keep your PATH modified after running the sniff as shown below:
$> ./configure-backend.py --sniff
You can run this step multiple times if you need to adjust your PATH or you install new office applications that you would like detected. Changes that you make by hand to the backends configuration line and other lines in ../conf/config.ini will be overwritten if you run the --sniff phase again.
- Have a look at your ../conf/config.ini file. You will need to set the factory_name to the factory name you created on Officeshots in step 3. The detected office applications are listed in the backends key of the global section. The cryptography library to use, log file location, and SSL client certificate location should have all been detected and set for you automatically by the sniffing phase. To tell the Officeshots server which applications your factory has configured you can use the --uploadconfig option to configure-backend.py.
$> ./configure-backend.py --email@example.com --password=foo --uploadconfig
You can run this step many times and duplicates of the same backend+version should not be created.
- OPTIONAL: You can perform a local test of one or more of the backends that your factory will be offering. See Factory Manual: Local document conversion for details.
- Start the factory. The below commands will start the factory on Linux, OSX, and Windows. The subsequent commands include command line options that you might also find useful.
Linux or OSX:
$> ./factory.py $> ./factory.py --debug
On Windows PowerShell?. The skip-certificate-checks allows the factory to start even if there are issues reported by the Python SSL implementation for the server certificate.
$> python ./factory.py $> python ./factory.py --skip-certificate-checks
See also Running the standard factory.
Older, manual installation steps
These are the manual steps which were the method to setting things up prior to July 2015.
- Log in on the Officeshots website, create a new factory, give it a nice name and add application workers to it. Add separate applications within a suite (like LibreOffice or Apache Open Office Calc, Impress and Writer) separately. See Configuring your factory.
- Install helper applications if needed. For instance with Apache Open Office and LibreOffice you need Python and the Python UNO bridge. Windows users need Python 2.6 and can find the UNO bridge when the choose Custom install
when installing the application. UNIX or Linux users will want to install the Python M2Crypto library as well.
- Download the latest Officeshots factory using Subversion. If you do not have Subversion then you can download a tar.gz package, but Subversion is better.
$> svn checkout http://code.officeshots.org/officeshots/trunk/factory
- Copy conf/config.default.ini to conf/config.ini. Set the correct path for your SSL key and certificate file. Linux users should make
sure that log_file is writeable or change the path. Windows users should set transport to pyssl and set correct paths for log_file
and tmp_files. See Configuring backends.
- In the oooserver- sections, check that the version number is correct. Windows users should also remove the ooo_host and ooo_port options
and uncomment the ooo_pipe option. See OOOServer.
- If you need to start a server, do so now. For instance start LibreOffice or Apache OpenOffice? in headless mode. Linux users can execute:
$> soffice -headless -nologo -norestore \ -accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManagerWindows users should edit utils/oooserver.bat and run that file. See Running OpenOffice.org in headless mode.
- Start the factory. On Linux, simply run the src/factory.py script. On windows, edit utils/ooofactory.bat and execute it. See Running the standard factory.
After all that, your factory should be up and running. If it does not, please read the remaining chapters of this manual or ask us for help on the Officeshots mailinglist.