Changeset 160


Ignore:
Timestamp:
05/19/09 15:20:04 (12 years ago)
Author:
sander
Message:

Upgrade factory manual to beta status

Location:
trunk/doc
Files:
1 added
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/Makefile

    r67 r160  
    2626                --stringparam section.label.includes.component.label 1 \ 
    2727                --stringparam admon.graphics 1 \ 
    28                 /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl \ 
     28                factory.html.xsl \ 
    2929                factory.xml 

  • trunk/doc/factory.xml

    r152 r160  
    103103        </preface> 
    104104 
     105        <chapter id="quickstart"> 
     106                <title>Quickstart</title> 
     107                <para> 
     108                        For the impatient, here follows a quick rundown of the steps that you need to do in order to run your own Officeshots 
     109                        factory for OpenOffice.org on Linux or Windows. 
     110                </para> 
     111                <orderedlist> 
     112                        <listitem> 
     113                                <para> 
     114                                        Register for an account on the Officeshots website, activate your acount and let us know that you 
     115                                        want to run a factory. See <xref linkend="accounts" />. 
     116                                </para> 
     117                        </listitem> 
     118                        <listitem> 
     119                                <para> 
     120                                        Get an SSL client certificate if you do not have one yet. See <xref linkend="cacert" />. 
     121                                </para> 
     122                        </listitem> 
     123                        <listitem> 
     124                                <para> 
     125                                        Log in on the Officeshots website, create a new factory, give it a nice name and add application workers to it. Add 
     126                                        OpenOffice.org Calc, Impress and Writer separately. See <xref linkend="webconfig" />. Linux users, please 
     127                                        check if you need to add OpenOffice.org or Go-OO. 
     128                                </para> 
     129                        </listitem> 
     130                        <listitem> 
     131                                <para> 
     132                                        Install OpenOffice.org, Python and the Python UNO bridge. Windows users need Python 2.6 and can find the 
     133                                        UNO bridge when the choose <guimenuitem>Custom install</guimenuitem> when installing OpenOffice.org. Linux 
     134                                        users will want to install the Python M2Crypto library as well. 
     135                                </para> 
     136                        </listitem> 
     137                        <listitem> 
     138                                <para> 
     139                                        Download the latest Officeshots factory using Subversion. If you do not have Subversion then you can 
     140                                        <ulink type="http" url="http://code.officeshots.org/viewvc.py/officeshots/trunk/factory/?view=tar">download a tar.gz package</ulink>, but 
     141                                        Subversion is better. 
     142                                </para> 
     143                                <screen> 
     144                                        <prompt>$&gt;</prompt> <userinput>svn checkout http://code.officeshots.org/officeshots/trunk/factory</userinput> 
     145                                </screen> 
     146                        </listitem> 
     147                        <listitem> 
     148                                <para> 
     149                                        Copy <filename>conf/config.default.ini</filename> to <filename>conf/config.ini</filename>. Set the correct path 
     150                                        for your SSL key and certificate file. Linux users should make sure that <parameter>log_file</parameter> is writeable or 
     151                                        change the path. Windows users should set <parameter>transport</parameter> to <parameter>pyssl</parameter> and set correct paths 
     152                                        for <parameter>log_file</parameter> and <parameter>tmp_files</parameter>. See <xref linkend="backend-config" />. 
     153                                </para> 
     154                        </listitem> 
     155                        <listitem> 
     156                                <para> 
     157                                        In the oooserver- sections, check that the version number is correct. Windows users should also remove the 
     158                                        <parameter>ooo_host</parameter> and <parameter>ooo_port</parameter> options and uncomment the <parameter>ooo_pipe</parameter> option. 
     159                                        See <xref linkend="oooserver" />. 
     160                                </para> 
     161                        </listitem> 
     162                        <listitem> 
     163                                <para> 
     164                                        Start OpenOffice.org in headless mode. Linux users can execute: 
     165                                </para> 
     166                                <screen> 
     167                                        <prompt>$&gt;</prompt> <userinput>soffice -headless -nologo -norestore -accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager</userinput> 
     168                                </screen> 
     169                                <para> 
     170                                        Windows users should edit <filename>utils/oooserver.bat</filename> and run that file. See <xref linkend="oooheadless" />. 
     171                                </para> 
     172                        </listitem> 
     173                        <listitem> 
     174                                <para> 
     175                                        Start the factory. On Linux, simply run the <filename>src/factory.py</filename> script. On windows, edit 
     176                                        <filename>utils/ooofactory.bat</filename> and execute it. See <xref linkend="run-factory" />. 
     177                                </para> 
     178                        </listitem> 
     179                </orderedlist> 
     180                <para> 
     181                        After all that, your factory should be up and running. If it does not, please read the remaining chapters of this manual or 
     182                        ask us for help on the <ulink type="http" url="http://lists.opendocsociety.org/mailman/listinfo/officeshots">Officeshots mailinglist</ulink>. 
     183                </para> 
     184        </chapter> 
     185 
    105186        <chapter id="accounts"> 
    106187                <title>Setting up your account</title> 
    107                 <note> 
    108                         <para> 
    109                                 At the moment the production server is not online yet. You can create an account on the development server 
    110                                 at <ulink type="http" url="http://dev.officeshots.org/users/register">http://dev.officeshots.org/users/register</ulink> 
    111                                 but you will need to re-register on the production server when it goes online. 
    112                         </para> 
    113                 </note> 
    114188                <para> 
    115189                        If you want to run a factory then you will first need to create an account at the central server and set it up 
    … …  
    134208                                </para> 
    135209                        </note> 
     210                        <section id="cacert"> 
     211                                <title>Get an SSL Certificate from CACert</title> 
     212                                <para> 
     213                                        If you do not have an SSL client certificate then you can easily get one for free from 
     214                                        <ulink type="http" url="http://www.cacert.org">CACert</ulink>. Go to the website of CACert and 
     215                                        register for an account. When you have an account, login and in the menu go to <guimenuitem>Client Certificates</guimenuitem>. 
     216                                        Create a new certificate and make sure you add your e-mail address to it. When CACert has created a certificate 
     217                                        for you then you can import it in your browser by clicking a link. 
     218                                </para> 
     219                                <para> 
     220                                        Your certificate is now in your browser. If you want, you can use it to automatically login to the 
     221                                        officeshots website. To do that, visit <ulink type="http" url="https://www.officeshots.org">https://www.officeshots.org</ulink>. 
     222                                </para> 
     223                        </section> 
     224                        <section> 
     225                                <title>Export your SSL Certificate from your browser</title> 
     226                                <para> 
     227                                        If you want to run a factory then you need to export your certificate from your browser and convert it into PEM 
     228                                        format which our factory understands. In Firefox, to to <guimenuitem>Preferences</guimenuitem>, <guimenuitem>Advanced</guimenuitem>, 
     229                                        <guimenuitem>View Certificates</guimenuitem>, <guimenuitem>Your Certificates</guimenuitem>. Click on your certificate and click 
     230                                        <guimenuitem>Backup</guimenuitem>. You will be asked to create a password to protect your certificate. Thawte has 
     231                                        <ulink type="http" url="https://search.thawte.com/support/ssl-digital-certificates/index?page=content&amp;id=SO552">instructions for Internet Explorer</ulink>. 
     232                                </para> 
     233                                <para> 
     234                                        You now have a .p12 or a .pfx file with your certificate. The last step is to convert this to PEM format. You can do this with 
     235                                        <application>OpenSSL</application>. Linux systems usually have this installed. Windows users will need to install OpenSSL themselves 
     236                                        or ask a friend who uses Linux to convert the certificate for them. The command to convert the certificate is: 
     237                                </para> 
     238                                <screen> 
     239                                        <prompt>$&gt;</prompt> <userinput>openssl pkcs12 -in certificate.p12 -out certificate.pem -clcerts</userinput> 
     240                                </screen> 
     241                                <para> 
     242                                        You will be asked to enter your backup password to read the .p12 or .pfx file and create a new password to encrypt the PEM file. 
     243                                        Alternatively, if you do not want to encrypt the PEM file then you can use the following command. 
     244                                </para> 
     245                                <screen> 
     246                                        <prompt>$&gt;</prompt> <userinput>openssl pkcs12 -in certificate.p12 -out certificate.pem -clcerts -nodes</userinput> 
     247                                </screen> 
     248                                <para> 
     249                                        Using an unencrypted PEM file is not as safe. If you have the M2Crypto python library on your computer then you can use 
     250                                        an encrypted PEM file. If you do not have M2Crypto then you will need an unencrypted PEM file because the standard Python SSL 
     251                                        library cannot remember your password for you. 
     252                                </para> 
     253                        </section> 
    136254                </section> 
    137                 <section> 
     255                <section id="webconfig"> 
    138256                        <title>Configuring your factory</title> 
     257                        <para> 
     258                                After the <application>Officeshots.org</application> staff have enabled your account for factory usage you can add factories to 
     259                                your account. A factory is a single computer that you have that participates in <application>Officeshots.org</application>. If 
     260                                you want to supply a Windows XP machine, a Linux machine and a smartphone then you would create three 
     261                                factories. To create a new factory, go to the Officeshots website and in the menu click <guimenuitem>Factories</guimenuitem> and then 
     262                                <guimenuitem>Add another factory</guimenuitem>. Then pick a name for it and fill in the hardware and operatingsystem fields. 
     263                        </para> 
     264                        <para> 
     265                                Next you can start adding workers to your factory. A worker is a specific office application that 
     266                                runs on your factory. If your Linux machine has OpenOffice.org and Gnumeric installed then you would 
     267                                add four factories: OpenOffice.org Writer, OpenOffice.org Calc, OpenOffice.org Impress and Gnumeric. 
     268                                For every worker you need to select which office application it provides and the version number. The version 
     269                                number can be any string, such as <parameter>2.4</parameter> or <parameter>2003 SP2</parameter>. 
     270                        </para> 
     271                        <note> 
     272                                <para id="gooo"> 
     273                                        If you run OpenOffice.org on Linux then you need to be careful which one you pick. Many distributions of Linux do 
     274                                        not ship OpenOffice.org but Go-OO. Go-OO is a version of OpenOffice.org that is built by Novell and it is different 
     275                                        from the standard OpenOffice.org. If you are running Ubuntu, Debian, Frugalware or Gentoo then you are running 
     276                                        Go-OO and not OpenOffice.org. Please pick Go-OO in the application dropdown. 
     277                                </para> 
     278                        </note> 
    139279                        <note> 
    140280                                <para> 
    … …  
    146286                                </para> 
    147287                        </note> 
    148                         <para> 
    149                                 After the <application>Officeshots.org</application> staff have enabled your account for factory usage you can add factories to 
    150                                 your account. A factory is a single computer that you have that participates in <application>Officeshots.org</application>. If 
    151                                 you want to supply a Windows XP machine, a Linux machine and a smartphone then you would create three 
    152                                 factories. 
    153                         </para> 
    154                         <para> 
    155                                 Next you can start adding workers to your factories. A worker is a specific office application that 
    156                                 runs on your factory. If your Linux machine has OpenOffice.org and Gnumeric installed then you would 
    157                                 add four factories: OpenOffice.org Writer, OpenOffice.org Calc, OpenOffice.org Impress and Gnumeric. 
    158                                 For every worker you need to select which office application it provides and the version number. The version 
    159                                 number can be any string, such as <parameter>2.4</parameter> or <parameter>2003 SP2</parameter>. 
    160                         </para> 
    161288                </section> 
    162289        </chapter> 
    … …  
    173300                        <title>Downloading and installing the standard factory</title> 
    174301                        <para> 
    175                                 You can download the standard factory from the <application>Officeshots.org</application> website or get the latest version from our 
    176                                 Subversion repository at <ulink type="http" url="https://svn.jejik.com/officeshots">https://svn.jejik.com/officeshots</ulink>. 
    177                         </para> 
    178                         <para> 
    179                                 Extract the package in a convenient location and copy <filename>conf/config.default.ini</filename> to <filename>conf/config.ini</filename> and open it in a 
     302                                You can download the standard factory from our Subversion repository at <ulink type="http" url="http://code.officeshots/officeshots">http://code.officeshots.org/officeshots</ulink>. 
     303                                You can also <ulink type="http" url="http://code.officeshots.org/viewvc.py/officeshots/trunk/factory/?view=tar">download a tar.gz package</ulink> but it is easier to keep up-to-date 
     304                                when you download it from Subversion. Use the following command to download the latest version of the factory from Subversion: 
     305                        </para> 
     306                        <screen> 
     307                                <prompt>$&gt;</prompt> <userinput>svn checkout http://code.officeshots.org/officeshots/trunk/factory</userinput> 
     308                        </screen> 
     309                        <para> 
     310                                To update your factory to the latest version, go to the directory where the factory is and run: 
     311                        </para> 
     312                        <screen> 
     313                                <prompt>$&gt;</prompt> <userinput>svn update</userinput> 
     314                        </screen> 
     315                        <para> 
     316                                Next, copy <filename>conf/config.default.ini</filename> to <filename>conf/config.ini</filename> and open it in a 
    180317                                text editor. Change the settings in the global section according to your preferences. 
    181318                        </para> 
    … …  
    186323                                        <listitem> 
    187324                                                <para> 
    188                                                         The name of your factory. This must match the factory name that you registered on 
     325                                                        The name of your factory. This must match the name of the factory that you created on 
    189326                                                        the website. You can pick any name you like but all your factories must have a different 
    190327                                                        name. 
    … …  
    263400                                                <para> 
    264401                                                        The maximum system load. If the system load is greater than this value then the factory will sleep 
    265                                                         instead of poll for new jobs. 
     402                                                        instead of poll for new jobs. This has currently no effect on Windows. 
    266403                                                </para> 
    267404                                        </listitem> 
    … …  
    278415                                        <term>backends</term> 
    279416                                        <listitem> 
    280                                                 <para>A comma separated list of backends that are enabled. See below for more information about backends.</para> 
     417                                                <para> 
     418                                                        A comma separated list of backends (applications) that are enabled. For every worker that you added to your 
     419                                                        factory on the server you should have a backend in your configuration file. See below for more information about backends. 
     420                                                </para> 
    281421                                        </listitem> 
    282422                                </varlistentry> 
    283423                        </variablelist> 
    284424                </section> 
    285                 <section> 
     425                <section id="backend-config"> 
    286426                        <title>Configuring backends</title> 
    287427                        <para> 
    288                                 For every enabled backend you need a section in your configuration file that configures the worker. The name of the 
    289                                 backend must be equal to the name given in the backends parameter in the global section. All backends have at least 
    290                                 a few configuration options in common. 
     428                                For every worker that you added to your factory on the Officeshots website you should have a backend in your configuration 
     429                                file. You can name the backends any way you like. Add them all to the <parameter>backends</parameter> in a comma separated list. Then, for all the backends 
     430                                in that list you need to have a separate configuration section. For example, if you added <application>AbiWord</application> and <application>Gnumeric</application> as 
     431                                workers on the Officeshots website then you need two backends in your configuration file. 
     432                        </para> 
     433                        <example> 
     434                                <title>Example configuration</title> 
     435                                <programlisting> 
     436<![CDATA[ 
     437[Global] 
     438backends = my_abiword, some_old_gnumeric 
     439 
     440[my_abiword] 
     441# Configuration options for AbiWord 
     442 
     443[some_old_gnumeric] 
     444# Configuration options for Gnumeric 
     445]]> 
     446                                </programlisting> 
     447                        </example> 
     448                        <para> 
     449                                If you do not want to use certain backends/sections then you only need to remove them from the <parameter>backends</parameter> line. You do not need to 
     450                                remove the entire sections. All the backends have at least a few configuration options in common. 
    291451                        </para> 
    292452                        <variablelist> 
    … …  
    339499                                        <listitem> 
    340500                                                <para> 
    341                                                         The name of the backend that implements the worker. See the next section on which backends 
     501                                                        The name of the Python backend class that implements the worker. See the next section on which backends 
    342502                                                        are available. 
    343503                                                </para> 
    … …  
    349509                                backend type. 
    350510                        </para> 
    351                         <section> 
     511                        <section id="oooserver"> 
    352512                                <title>OOOServer</title> 
    353513                                <para> 
    354514                                        The OOOServer backends implements OpenOffice.org running in headless mode. As such it is not able to 
    355                                         produce screenshots but it can produce ODF roundtrip and PDF faster than the VNC-powered OpenOffice.org 
    356                                         can. 
    357                                 </para> 
    358                                 <para> 
    359                                         In order to use the OOOServer you will need to create a new user on your system and start OpenOffice.org 
    360                                         in headless mode before you start the factory. In order to use OpenOffice.org in headless mode on a Linux 
    361                                         or BSD system you will need to have a virtual framebuffer such as xvfb. In the utils directory of the 
    362                                         factory package there is an oooserver init script that can be used to start and stop OpenOffice.org 
    363                                         in headless mode. See <xref linkend="oooserver-init" />. 
    364                                 </para> 
    365                                 <para> 
    366                                         Besides the standard configuration options, you need to set the following options for the OOOServer 
     515                                        produce screenshots but only ODF roundtrip and PDF export. To use the OOOServer backend you must have 
     516                                        OpenOffice.org running in headless mode. See <xref linkend="oooheadless" />. 
     517                                </para> 
     518                                <para> 
     519                                        Besides the standard configuration options, you can set the following options for the OOOServer 
    367520                                        backend. 
    368521                                </para> 
    … …  
    372525                                                <listitem> 
    373526                                                        <para> 
    374                                                                 The hostname of the machine that OpenOffice.org is running in headless mode. 
    375                                                                 Normally this should be localhost. 
     527                                                                The hostname of the machine that OpenOffice.org is running on in headless mode. 
     528                                                                Normally this should be <parameter>localhost</parameter>. If you set this option 
     529                                                                then you should also set the <parameter>ooo_port</parameter> option. 
    376530                                                        </para> 
    377531                                                </listitem> 
    … …  
    386540                                                </listitem> 
    387541                                        </varlistentry> 
     542                                        <varlistentry> 
     543                                                <term>ooo_pipe</term> 
     544                                                <listitem> 
     545                                                        <para> 
     546                                                                The name of the pipe that OpenOffice.org is listening to. If you set this 
     547                                                                option then you should not set the <parameter>ooo_host</parameter> and 
     548                                                                <parameter>ooo_port</parameter> options. 
     549                                                        </para> 
     550                                                </listitem> 
     551                                        </varlistentry> 
    388552                                </variablelist> 
    389                                 <section id="oooserver-init"> 
    390                                         <title>OOOServer init script</title> 
     553                                <note> 
    391554                                        <para> 
    392                                                 The <application>oooserver</application> init script in the <filename class="directory">utils</filename> directory 
    393                                                 can be used to automatically start and stop OpenOffice.org in headless mode on a Unix/Linux machine. 
    394                                                 Place this file in your <filename class="directory">/etc/init.d</filename> directory and make it executable. Then you 
    395                                                 need to add symlinks to it in the appropriate places. This varies from distribution to distribution. On Debian and 
    396                                                 derivatives like Ubuntu you can execute the following command (as root) to create these symlinks: 
     555                                                On Windows XP and Vista it is not possible to connect to OpenOffice.org using a socket with the <parameter>ooo_host</parameter> and 
     556                                                <parameter>ooo_port</parameter> options. You should use a pipe instead. 
     557                                        </para> 
     558                                </note> 
     559                                <section id="oooheadless"> 
     560                                        <title>Running OpenOffice.org in headless mode</title> 
     561                                        <para> 
     562                                                When OpenOffice.org is running in headless mode you cannot start it yourself anymore. The easiest thing to do is to create 
     563                                                a new user on your computer and run OpenOffice.org in headless mode under that user account instead of your own. 
     564                                                Linux users can start OpenOffice.org in headless mode using the following command: 
    397565                                        </para> 
    398566                                        <screen> 
    399                                                 <prompt>~#</prompt> <userinput><command>update-rc.d</command> <filename>oooserver</filename> defaults</userinput> 
     567                                                <prompt>$&gt;</prompt> <userinput>soffice -headless -nologo -norestore -accept=socket,host=localhost,port=8100;urp;StarOffice.ServiceManager</userinput> 
    400568                                        </screen> 
    401569                                        <para> 
    402                                                 You will also need to configure the oooserver init script. By default oooserver will run as user <parameter>nobody</parameter> 
    403                                                 but on many systems this user does not have a valid home directory. <application>OpenOffice.org</application> does not start 
    404                                                 without a valid home directory. Either make sure user <parameter>nobody</parameter> exists and has a valid home 
    405                                                 directory, or change the <parameter>USER</parameter> parameter in the oooserver init script. 
     570                                                For Windows users there is a simple batch file in the utils directory called <filename>utils/oooserver.bat</filename>. Simply edit that file, 
     571                                                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 
     572                                                to start OpenOffice.org in headless mode. If you want to start OpenOffice.org manually on Windows then you can execute the following command: 
    406573                                        </para> 
     574                                        <screen> 
     575                                                <prompt>$&gt;</prompt> <userinput>soffice.exe -headless -nologo -norestore "-accept=pipe,name=officeshots;urp;StarOffice.ServiceManager"</userinput> 
     576                                        </screen> 
     577                                        <note> 
     578                                                <para> 
     579                                                        Sometimes OpenOffice.org on Windows does not install the Python UNO bridge. You can re-install OpenOffice.org. Make sure you choose <guimenuitem>Custom install</guimenuitem> 
     580                                                        amd check the box that installs Python UNO. 
     581                                                </para> 
     582                                        </note> 
     583                                        <section id="oooserver-init"> 
     584                                                <title>OOOServer init script for Debian/Ubuntu</title> 
     585                                                <para> 
     586                                                        The <application>oooserver</application> init script in the <filename class="directory">utils</filename> directory 
     587                                                        can be used to automatically start and stop OpenOffice.org in headless mode on a Debian or Ubuntu machine. It uses <application>xvbf</application>, the 
     588                                                        X Virtual FrameBuffer so it can even run on a machine that has no complete X Server installed such as most servers. 
     589                                                        Place this file in your <filename class="directory">/etc/init.d</filename> directory and make it executable. Then you 
     590                                                        need to add symlinks to it in the appropriate places. You can execute the following command (as root) to create these symlinks automatically: 
     591                                                </para> 
     592                                                <screen> 
     593                                                        <prompt>#&gt;</prompt> <userinput><command>update-rc.d</command> <filename>oooserver</filename> defaults</userinput> 
     594                                                </screen> 
     595                                                <para> 
     596                                                        You will also need to configure the oooserver init script. By default oooserver will run as user <parameter>nobody</parameter> 
     597                                                        but on many systems this user does not have a valid home directory. <application>OpenOffice.org</application> does not start 
     598                                                        without a valid home directory. Either make sure user <parameter>nobody</parameter> exists and has a valid home 
     599                                                        directory, or change the <parameter>USER</parameter> parameter in the oooserver init script. 
     600                                                </para> 
     601                                        </section> 
    407602                                </section> 
    408603                        </section> 
    … …  
    542737                        </section> 
    543738                </section> 
    544                 <section> 
     739                <section id="run-factory"> 
    545740                        <title>Running the standard factory</title> 
    546741                        <para> 
    … …  
    564759                                        <listitem> 
    565760                                                <para> 
    566                                                         Full path to the configuration file to use. Bu default conf/config.ini is used. 
     761                                                        Full path to the configuration file to use. By default conf/config.ini is used. 
    567762                                                </para> 
    568763                                        </listitem> 
    … …  
    580775                                </varlistentry> 
    581776                        </variablelist> 
     777                        <note> 
     778                                <para> 
     779                                        If you are running OpenOffice.org on Windows then you must run the factory.py script with the Python version 
     780                                        that was installed by OpenOffice.org. The Python UNO bridge does not work with any other version of Python on Windows. 
     781                                        However, you do need the other libraries from the standard Python since the OpenOffice.org version of Python does not 
     782                                        understand SSL connections. 
     783                                </para> 
     784                                <para> 
     785                                        To make this easier for Windows users, there is a script called <filename>utils/ooofactory.bat</filename> that automatically 
     786                                        starts the factory with the correct Python versions and libraries. Make sure you have Python 2.6 installed. Then edit the <filename>ooofactory.bat</filename> 
     787                                        script and make sure that the paths to Python 2.6 and OpenOffice.org are correct. The double-click the file to start the factory. 
     788                                </para> 
     789                        </note> 
    582790                </section> 
    583791        </chapter> 

  • trunk/doc/odf-shots-proposal.tex

    r3 r160  
    33\hyphenation{Open-Office} 
    44 
    5 \title{ODF-Shots project proposal} 
     5\title{Officeshots project proposal} 
    66\author{Sander Mar\'echal, Stichting Lone Wolves\\ 
    77  \texttt{s.marechal@jejik.com}} 
    … …  
    1515In an ideal world, all these ODF implementations would be fully compatible with each other and with the published standard. Unfortunately in the real world, multiple ODF versions with implementation-defined parts, software bugs and other inconsistencies present document designers and authors with many of the same problems that HTML authors face on the world wide web. Different applications may display and handle ODF documents in different ways. OASIS has formed the ``OASIS Open Document Format Interoperability and Conformance (OIC) TC''\footnote{http://www.oasis-open.org/committees/tc\_home.php?wg\_abbrev=oic} to combat this problem in the long term, but for the short term a different solution must be found. 
    1616 
    17 This plan proposes to create a service called ``ODF-Shots'' which lets ODF authors and designers upload documents to a webservice and see how different office suites render their documents. This allows authors of complex documents and designers of ODF templates to ensure that their documents work under many different office suites. The service works in a manner similar to Browsershots\footnote{http://browsershots.org/} where HTML authors can ensure that their designs work under many different browser versions. 
     17This plan proposes to create a service called ``Officehots'' which lets ODF authors and designers upload documents to a webservice and see how different office suites render their documents. This allows authors of complex documents and designers of ODF templates to ensure that their documents work under many different office suites. The service works in a manner similar to Browsershots\footnote{http://browsershots.org/} where HTML authors can ensure that their designs work under many different browser versions. 
    1818 
    1919\section{Service overview} 
    2020 
    21 The ODF-Shots service will consist of a central server where authors can upload their documents and which will manage the processing queues. The actual rendering as PDF documents or a series of screenshots will be performed by one or more processing clients. The central server and the various processing clients communicate through a simple webservice API. The goal of this project is to provide the central server and a complete API specification for the processing clients. The actual processing clients should be implemented by volunteers or companies who want to contribute to this project. 
     21The Officeshots service will consist of a central server where authors can upload their documents and which will manage the processing queues. The actual rendering as PDF documents or a series of screenshots will be performed by one or more processing clients. The central server and the various processing clients communicate through a simple webservice API. The goal of this project is to provide the central server, a complete API specification for the processing clients and a standard implementation of the processing client. The actual processing clients can be implemented by volunteers or companies who want to contribute to this project. They can base their clients on the default client stack provided by the Officeshots project or write their own using the webservice API directly. 
    2222 
    2323\subsection{Central server} 
    … …  
    3333\section{Security} 
    3434 
    35 There are three security issues to consider with the ODF-Shots project. First, documents that were uploaded by authors should be treated in a private manner. While it is never recommended that authors upload confidential documents to a public web service, authors should reasonable be able to assume that only the processing clients and not the entire world can access their documents or the rendering results. The second security issue are macro viruses and other malware that can be embedded inside ODF documents. Processing clients should be reasonably secure so that the documents they are processing will not harm their servers or contribute to the spread of malware. The third and last security issue are denial of service attacks. 
     35There are three security issues to consider with the Officeshots project. First, documents that were uploaded by authors should be treated in a private manner. While it is never recommended that authors upload confidential documents to a public web service, authors should reasonable be able to assume that only the processing clients and not the entire world can access their documents or the rendering results. The second security issue are macro viruses and other malware that can be embedded inside ODF documents. Processing clients should be reasonably secure so that the documents they are processing will not harm their servers or contribute to the spread of malware. The third and last security issue are denial of service attacks. 
    3636 
    3737\subsection{Privacy for authors} 
    3838 
    39 Authors should reasonably expect that the documents they upload cannot be accessed by the entire world. ODF-Shots does not guarantee confidentiality and strongly discourages uploading confidential documents, but under normal circumstances an author should expect that he or she is the only person to see the document or the rendering results. 
     39Authors should reasonably expect that the documents they upload cannot be accessed by the entire world. Officeshots does not guarantee confidentiality and strongly discourages uploading confidential documents, but under normal circumstances an author should expect that he or she is the only person to see the document or the rendering results. 
    4040 
    41 When an author uploads a document to the ODF-Shots server he will receive a unique and unpredictable token that allows the author to view the results. These tokens are possibly tied to an account that the author needs to create on the service first. It has yet to be determined if accounts will be required for authors. 
     41When an author uploads a document to the Officeshots server he will receive a unique and unpredictable token that allows the author to view the results. These tokens are possibly tied to an account that the author needs to create on the service first. It has yet to be determined if accounts will be required for authors. 
    4242 
    43 Accounts will be required for processing clients. This allows us to screen the provider of processing clients before his services are added to the ODF-Shots network. The exact requirements of the screening have yet to be determined. Each provider will be issued a security key or certificate that allows him to register his processing client(s) with the central ODF-Shots server. These keys or certificates will be used for authentication as well as encryption of the communication between the central server and the processing clients. 
     43Accounts will be required for processing clients. This allows us to screen the provider of processing clients before his services are added to the Officeshots network. The exact requirements of the screening have yet to be determined. Each provider will be issued a security key or certificate that allows him to register his processing client(s) with the central Officeshots server. These keys or certificates will be used for authentication as well as encryption of the communication between the central server and the processing clients. 
    4444 
    4545\subsection{Malware protection} 
    … …  
    4949\subsection{Denial of service} 
    5050 
    51 Denial of service attacks are attacks whereby a malicious author uploads a document to the ODF-Shots service that is specifically crafted to crash or otherwise harm one of the processing clients. It is also possible that a non-malicious author uploads a document that cannot be rendered properly by the processing client and in the process either crashes the office suite or makes it consume too much resources. 
     51Denial of service attacks are attacks whereby a malicious author uploads a document to the Officeshots service that is specifically crafted to crash or otherwise harm one of the processing clients. It is also possible that a non-malicious author uploads a document that cannot be rendered properly by the processing client and in the process either crashes the office suite or makes it consume too much resources. 
    5252 
    53 Not much can be done about these attacks on the central ODF-Shots server except scanning for known malicious documents. Implementors of processing clients are encouraged to use and write tools that monitor the execution of the jobs they process and halt processing when resources soar or a denial of service attack is suspected. They are also encouraged to set resource limits in any way they see fit. 
     53Not much can be done about these attacks on the central Officeshots server except scanning for known malicious documents. Implementors of processing clients are encouraged to use and write tools that monitor the execution of the jobs they process and halt processing when resources soar or a denial of service attack is suspected. They are also encouraged to set resource limits in any way they see fit. 
    5454 
    55 It may be possible to enforce certain limits on the central ODF-Shots server before documents are queued, such as maximum filesize or limits on the number of pages to be processed or returned, but these have yet to be determined. The initial version of ODF-Shots will not enforce such limits but later revision may do so in response to the experience of processing clients. 
     55It may be possible to enforce certain limits on the central Officeshots server before documents are queued, such as maximum filesize or limits on the number of pages to be processed or returned, but these have yet to be determined. The initial version of Officeshots will not enforce such limits but later revision may do so in response to the experience of processing clients. 
    5656 
    5757\section{Implementation plan} 
    … …  
    5959The project will start with the design of the API and a basic implementation of the central server. At least one developer must be found who is willing to provide an initial processing server. This can be used to test the API, uncover any shortcomings and fix them before there are many processing clients. The main focus in this stage is the design and implementation of the API between the central server and the processing clients. 
    6060 
    61 After the API design has been completed and tested, the central server can be extended to provide a real-world user interface for the authors. At the same time other parties should be approached for implementing additional processing clients. When this has been completed the service can be put into production. 
     61After the API design has been completed and tested, the central server can be extended to provide a real-world user interface for the authors. At the same time other parties should be approached for implementing additional processing clients.  We will also create a default processing client stack that external developers can use to speed up development, but they are not required to use this. 
    6262 
    63 In the final stages of this project the number of processing clients should be extended to cover as many different office suites as possible. There will undoubtedly be scalability issues that crop up and need to be solved. In order to attract more processing clients it would be useful to provide a standard processing client API library that developers can use to interface with the central server, as well as guides on how to set up and register new processing clients. 
     63Durng the third stage the central server and a small cloud of processing clients will be deployed for internal testing and eventual beta release. This cloud of clients ensures that a minimum number of clients will always be available to the users of Officeshots, regardless of external volunteers. When this has been completed the service can be put into production. 
     64 
     65In the final stages of this project the number of processing clients should be extended to cover as many different office suites and platforms as possible. There will undoubtedly be scalability issues that crop up and need to be solved. In order to attract more processing clients it would be useful to extend and package the standard processing client so that even non-developers can easily set up new processing clients. 
    6466 
    6567\end{document} 
Note: See TracChangeset for help on using the changeset viewer.