Setup Odisee Server 2 on Linux

Odisee is a document generation server using Apache OpenOffice or LibreOffice to produce documents.

Odisee® — Make Your Documents Smile.

Follow this installation process:

  1. Install LibreOffice
  2. Install Odise
  3. Configure Odisee to find your LibreOffice installation
  4. Start Odisee and test it by using Odisee Client

Install Prerequired Software

Odisee needs:

  • rsync
  • sed
  • sudo

Just install them at once:

apt-get install rsync sed sudo

Install LibreOffice

Just select your favorite installation method:

  1. Through a package manager, e.g. sudo apt-get install libreoffice
  2. Download a package from http://www.libreoffice.org

and install LibreOffice. See The Document Foundation, Wiki: Installing LibreOffice on Linux or Installation unter Linux (German) for details on installing LibreOffice under Linux.

Ubuntu

If you want to install another/the latest version of LibreOffice in Ubuntu, see this article on askubuntu.com and PPA for LibreOffice or PPA for LibreOffice 3.5.

sudo add-apt-repository ppa:libreoffice/libreoffice-3-5
sudo apt-get update
sudo apt-get dist-upgrade
sudo apt-get install libreoffice-writer

Install Odisee

First create group and user odisee. I choose /usr/local/odisee as the home and installation directory for Odisee, this directory is referred to as $ODISEE_HOME. Additionally you need bash 4 to support Odisee’s shell scripts, but this is default under Linux.

addgroup odisee
adduser --ingroup odisee --home /usr/local/odisee --shell /bin/bash --disabled-password --gecos "Odisee" odisee

Create installation directory and set permissions:

mkdir /usr/local/odisee
chown odisee:odisee /usr/local/odisee

Login as user odisee, e.g.

su - odisee

Download and unpack the Odisee Server distribution:

curl -LO http://files.odisee.de/odisee-server.tar.gz
tar xzf odisee-server.tar.gz

The extracted distribution should look like this:

[odisee@linux ~]$ ls -la
drwxr-x---  11 root    odisee   512 Mar  9 13:22 .
drwxr-xr-x  22 root    wheel    512 Mar  9 13:03 ..
-rw-r-----   1 odisee  odisee   261 Mar  8 14:45 .bash_profile
drwx------   2 odisee  odisee   512 Mar  8 14:37 .ssh
drwxr-x---   2 odisee  odisee   512 Mar  9 13:22 bin
drwxr-x---   3 odisee  odisee   512 Mar  8 15:43 etc
drwxr-x---   3 odisee  odisee   512 Nov 30  2012 lib
drwxr-x---   5 odisee  odisee   512 Mar  8 15:37 libexec
drwxr-x---   2 odisee  odisee   512 Nov 30  2012 license
drwxr-x---   3 odisee  odisee   512 Nov 30  2012 src
drwxr-x---   7 root    odisee   512 Dec 18  2012 var

sudo

Odisee should be able to use sudo to execute some commands as root. Use visudo to edit the file.

A typical /etc/sudoers looks like:

odisee ALL=(ALL) ALL, NOPASSWD: /bin/chmod, /bin/chown, /bin/mkdir, /bin/ps, /usr/sbin/service

Multitenancy

Odisee is multitenant, so users should be able to access their templates and generated documents. To achieve that, I favor use of SSH, a user can provide a SSH public key and get access.

Add this to your /etc/ssh/sshd_config to allow users in group odisee to access their data:

Subsystem sftp internal-sftp

Match User !odisee Group odisee
    ChrootDirectory %h
    ForceCommand internal-sftp

Adding Odisee Users

To add an Odisee user use odictl -c -u <username>:

[odisee@linux ~]$ odictl -c -u odiuser
User 'odiuser' created.

Do not forget to put user’s SSH public key into $ODISEE_HOME/var/user/odiuser/.ssh/authorized_keys.

Permissions

Directory permissions must be set appropriately for proper operation and to support multi tenancy through SCP/SFTP. For sshd configuration directive ChrootDirectory all directories on the path to the user directory must be owned by root and not writable by group or other. The command odictl -q set-perm does this job for you.

Access to HTTP Service

The user must have access to Odisee’s HTTP service which is secured by HTTP Basic Authentication. Edit $ODISEE_HOME/libexec/tomcat/conf/odisee-users.xml and add an entry for odiuser.

The distribution comes preconfigured with a user odisee so you can start testing.

<?xml version='1.0' encoding='utf-8'?>
<tomcat-users>
    <user username="odisee" password="odisee" roles="odisee"/>
</tomcat-users>

Configure LibreOffice in Odisee

Odisee can find LibreOffice installations by its own, just give it a try:

[odisee@linux ~]$ odictl -q find-inst
Installation path: /usr/lib/libreoffice
Java classpath: /usr/lib/libreoffice/ure-link/share/java/juh.jar:
                /usr/lib/libreoffice/ure-link/share/java/jurt.jar:
                /usr/lib/libreoffice/ure-link/share/java/ridl.jar:
                /usr/lib/libreoffice/program/classes/unoil.jar

If the above command succeeds, you can easily add LibreOffice instances through odictl. A typical instance is named like odi<N> and listens on localhost with a port starting at 2001:

[odisee@linux ~]$ odictl -c -i odi1
Instance 'odi1' added.

Manually Configure LibreOffice Instances

This is important when you need to tweak instance configuration. It is the case when your LibreOffice installation does not accept options (executable soffice) which are defined by default in Odisee.

LibreOffice 4.1

Example:

LibreOffice 4.1 does not recognize the option norestart which is set by default when an instance is added through odictl -c -i.

[odisee@linux ~]$ odictl -q start-inst -i odi2
Starting AOO/LO instance 'odi3' on 127.0.0.1:2003 using data directory /usr/local/odisee/var/profile/odi3
LibreOffice 4.1.5.3 410m0(Build:3)

Unknown option: --norestart

Usage: soffice [options] [documents...]

You configure LibreOffice instances in $ODISEE_HOME/etc/odiinst. The file contains the following information, each separated by a pipe |:

instance name|ip address|port|path to LibreOffice installation||options when starting LibreOffice executable|autostart?

Through this file distributed installations can be supported (Odisee and LibreOffice instances on different servers), but it should be optional in a future Odisee release.

To configure two LibreOffice instances use this:

odi1|127.0.0.1|2001|/usr/local/lib/libreoffice||nologo nodefault nolockcheck nocrashreport|true
odi2|127.0.0.1|2002|/usr/local/lib/libreoffice||nologo nodefault nolockcheck nocrashreport|true

If you need more instances, just duplicate the last line and set a new instance name (odi2 -> odi3) and increment the port number (2002 -> 2003).

Lifecycle

Odisee can be controlled through odictl.

Start

There are two components that need to be started: LibreOffice instance(s) and Odisee — a Java Web Container, Apache Tomcat by default. To start Odisee along with LibreOffice instances just use odictl -q start:

[odisee@linux ~]$ odictl -q start
Odisee(R)
...
Starting OpenOffice instance 'odi1' on 127.0.0.1:2001 using data directory /home/odisee/var/profile/odi1
Starting OpenOffice instance 'odi2' on 127.0.0.1:2002 using data directory /home/odisee/var/profile/odi2
Starting OpenOffice instance 'odi3' on 127.0.0.1:2003 using data directory /home/odisee/var/profile/odi3
Starting OpenOffice instance 'odi4' on 127.0.0.1:2004 using data directory /home/odisee/var/profile/odi4
Starting Odisee Service

Status

Query the status of your instance(s) with odictl -s:

[odisee@linux ~]$ odictl -s
Instance: odi1
  Status................. ONLINE, READY
  Process ID............. 23587
  Socket configuration... tcp://127.0.0.1:2001
    #listening........... 1
    #connections......... 0
  Home................... /usr/lib/libreoffice
  UserInstallation....... /usr/local/odisee/var/profile/odi1
  Options................ nologo nofirststartwizard invisible nodefault nolockcheck nocrashreport headless
  Autostart.............. true

Using Odisee

There’s a Windows client to test sending requests to Odisee. On the same page there are links to Odisee client libraries (Java, VB.NET, PHP) along with examples how to use the API.

Have fun!

This entry was posted in Odisee. Bookmark the permalink.