Installing eGroupware on FreeNAS

I have been using Stylite‘s eGroupware system for about a year now. Previously it was installed on an old laptop running OpenSuse (x86). One of my tasks after installing FreeNAS was to transfer the system from here to a jail.

The last few releases of FreeNAS have made installing additional systems easier with its jail architecture and I thought it would be a good opportunity to remove one more piece of hardware and take advantage of my FreeNAS box.

eGroupware itself is a very easy to use system. Like FreeNAS itself, it is released as both paid-for/supported versions, and a community edition. It’s an easy to use system, and the demands it makes are minimal. It connects to a range of IMAP and database systems.

Background

Current System

My current server is an old laptop (circa 2005), (which shows just how lean eGroupware is, and why I felt it would be a good candidaet to transfer across to FreeNAS).

Linux (OpenSuse, x86 architecture)
Apache 2
various support utilities (tnef,jpgraph and others)
postgres backend (already sitting on an existing FreeNAS jail)
local data files are located in the default /var/lib/egroupware directory
all communication via HTTPS

Proposed System

Based on a plain FreeNAS jail, a single purpose LAMP stack to serve out the eGroupware. The backend database is already installed in a seperate jail.

run in FreeNAS jail
Apache 2
same support utilities
move local data files to a location on the FreeNAS (so mount the directory into the jail. No data files kept in the jail)
All communication via HTTPS
Link to existing database

The plan was to simply migrate the system across and connect to the existing database. I’m using self-signed certificates for HTTPS, so these wrere transferred across directly. The address for the server is a DNS alias, so point this from the existing machine to the new one.

I also decided to use standard FreeNAS/FreeBSD packages (installed using the pkg command) rather than building eveything from scratch.

A quick word about my setup. FreeNAS was originally setup just a file server, so I have three 1TB drives configured as a ZFS RAID-5 configration. Once iXsystems introdcued the jail functionality, I added an additional 2 300GB drives in a mirrored array to hold any jails. Critical data in any jail is held on the RAID-5 array and mounted into the jails as required. This also prevents the accidental deletion of data if a jail is deleted. eGroupware will store files in the filesystem, so these files are held on the main data drive.

Installing eGroupware on FreeNAS

Build a jail to hold the system

Use the FreeNAS web administration screen to build the jail. Give it a good name (egroupware) and assign it a free IP address on your network. I don’t use IPv6, so I left that blank.

Jail Settings

name: groupware
Jail Type: Standard
IPv4 Address: your address
IPv4 Netmask: your netmask – probably /24(255.255.255.0.) for small networks
No IPv6 settings configured
Autostart: Yes (ticked)
VIMAGE: Yes (ticked)
NAT: No (unticked)
vanilla: No (unticked)

Wait for the jail to be built and then connect to it. You can either connect via the shell command at the web administration or use ssh. My preference is to use ssh to connect to the FreeNAS box and then connect to the jail from here.

joe@pp02:~> ssh root@freenas
.... login stuff .....
[root@freenas ~]# jls
   JID  IP Address      Hostname                      Path
.... list of running jails .....
    13  -               groupware                     /mnt/volume1/jails/groupware
[root@freenas ~]# jexec 13 /bin/csh
root@groupware:/ #

We are now in the jail and we can start installing everything. Because there is a FreeBSD eGroupware package already created, most of the heavy lifting, especially for installing all the dependencies is already taken care of.

root@groupware:/ # pkg install deskutils/egroupware
Updating repository catalogue
The following 34 packages will be installed:

        Installing tidy-lib: 090315.c_1
        Installing perl: 5.14.4
        Installing pcre: 8.33
        Installing libmcrypt: 2.5.8
        Installing libltdl: 2.4.2
        Installing cclient: 2007f,1
        Installing tnef: 1.4.9
        Installing apache22: 2.2.24
        Installing php5: 5.4.16
        Installing php5-session: 5.4.16
        Installing php5-xml: 5.4.16
        Installing pear: 1.9.4_1
        Installing php5-dom: 5.4.16
        Installing php5-ctype: 5.4.16
        Installing pear-Log: 1.12.7
        Installing php5-openssl: 5.4.16
        Installing php5-mcrypt: 5.4.16
        Installing pear-Auth: 1.6.4
        Installing pear-Net_Socket: 1.0.14
        Installing pear-Net_Sieve: 1.3.2
        Installing php5-imap: 5.4.16
        Installing php5-pdo: 5.4.16
        Installing php5-mysql: 5.4.16
        Installing php5-zlib: 5.4.16
        Installing php5-zip: 5.4.16
        Installing php5-bz2: 5.4.16
        Installing php5-tidy: 5.4.16
        Installing pear-HTTP_WebDAV_Server: 1.0.0.r4
        Installing php5-xmlreader: 5.4.16
        Installing pear-XML_Feed_Parser: 1.0.5
        Installing pear-Auth_SASL: 1.0.6
        Installing pear-Net_IMAP: 1.1.0
        Installing php5-pdo_mysql: 5.4.16
        Installing eGroupware: 1.8.004.20130620

The installation will require 140 MB more space

30 MB to be downloaded
The installation will require 140 MB more space

30 MB to be downloaded

This will install and build the environment.

This takes a minute or so depending on your internet connection speed. These messages (or something like them) will be shown at the end of the installation.

**** UPDATE ****

I use Thunderbird as my mail client, so I have only just discovered this dependency: In order to use the built-in eGroupware mail client (FelaMiMail), the php json package also needs to be installed.

pkg install php5-json-5.4.16
Updating repository catalogue
The following 1 packages will be installed:

        Installing php5-json: 5.4.16

The installation will require 51 kB more space

18 kB to be downloaded

Proceed with installing packages [y/N]: y

**** END UPDATE ****

To run apache www server from startup, add apache22_enable="YES"
in your /etc/rc.conf. Extra options can be found in startup script.

Your hostname must be resolvable using at least 1 mechanism in
/etc/nsswitch typically DNS or /etc/hosts or apache might
have issues starting depending on the modules you are using.
***************************************************************

Make sure index.php is part of your DirectoryIndex.

You should add the following to your Apache configuration file:

AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

***************************************************************

==============================================================
POST-INSTALL CONFIGURATION FOR eGroupware

Make sure in your php.ini session.save_path='/tmp' is writable
upload_max_filesize >= 8M

1) Create a user and a database for eGroupware to store all
   its tables in (or choose an existing database).
   It doesn't matter what the database or user names are,
   as this will be configured in a later step.

2) Add the following to your Apache configuration, and
   restart the server:

   ### Add the AcceptPathInfo directive only for Apache 2.0.30 or later.
   Alias /eg /usr/local/www/eg/
   AcceptPathInfo On
   <Directory /usr/local/www/eg>
      AllowOverride None
      Order Allow,Deny
      Allow from all 
   </Directory>
   <Directory /usr/local/www/egdata>
      AllowOverride None
      Order Allow,Deny
      Deny from all 
   </Directory>

3) Visit your eGroupware site with a browser (i.e.,
   http://your.server.com/eg/), and you should
   be taken to the install.php script, which will lead
   you through creating a config file and then
   setting up eGroupware, creating an admin account, etc.

4) When you come to the setup page,please set the files'
and backup's full path with:
   /usr/local/www/egdata/files
   /usr/local/www/egdata/backup

For more information, see the INSTALL DOCUMENTATION:

http://www.egroupware.org/index.php?page_name=wiki&lang=&wikipage=ManualSetup

======================================================

Add the Apache start line to the rc.conf. This will mean that Apache will start whenever teh jail is started. If you want to do this manually, then replace the “YES” with a “NO”. I’d recommend always adding this line, so the command is always there for when you come back months later.

root@groupware:/ # echo 'apache22_enable="YES"' >> /etc/rc.conf

I created /usr/local/etc/apache22/Includes/local.conf to add the settings for eGroupware that are described at the end of the installation.

# file: /usr/local/etc/apache22/Includes/egroupware.conf
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

I then created the file /usr/local/etc/apache22/egroupware.conf. This is a very basic configuration, but means that we can check everything is working before fine tuning it later if necessary.

The egroupware system is installed into /usr/local/www/eg. You will also see the directory /usr/local/www/egdata if you look in /usr/local/www.

The file /usr/local/etc/apache22/Includes/egroupware.conf:

  ### Add the AcceptPathInfo directive only for Apache 2.0.30 or later.
   Alias /eg /usr/local/www/eg/
   AcceptPathInfo On
   <Directory /usr/local/www/eg>
      AllowOverride None
      Order Allow,Deny
      Allow from all 
   </Directory>
   <Directory /usr/local/www/egdata>
      AllowOverride None
      Order Allow,Deny
      Deny from all 
   </Directory>

I will extend this later, but at this stage, this is enough to check that eGroupware is installed okay.

PHP setup

The version of php installed is 5.4.16. From the installation above, you can see that only the mysql php plugins were installed, so I needed to install the postgresql plugins. I also needed to make sure that I installed the same versions of the plugins; 5.4.16. If you just say pkg install php5-pdo_pgsql, the package manager will assume the latest version, which will throw up error messages because it is expecting a different (later) version of php to be present.

Configuring the `php.ini` File

You will see that the php installation puts two files into the /usr/local/etc directory: php.ini-development and php.ini-production.

I would suggest that you use the development file to test the installation and when you are happy replace this with the production version. The debug version may give you some more indicative error messages if you have problems installing. Note: The eGroupware configuration checking script will throw up some warnings when you use the development version of php.ini, because it picks up settings that shouldn’t be there in a production environment.

I would also suggest altering both the production and development files at this stage so that you don’t forget to alter the prodcution version when you switch and go live.

upload_max_filesize line in both files. I use 20M.
Update the time zone date.timezone = Europe/London

Copy php.ini-development to php.ini.

Configure PHP environment

Now install any additional required php modules. I use postgresql so i needed to add support for this. I also saw that the configuration checker explicitly requested the sqlite module for the calendar function.

root@groupware:/usr/local/etc # pkg install php5-pdo_pgsql-5.4.16 php5-pgsql-5.4.16
Updating repository catalogue
The following 2 packages will be installed:

        Installing php5-pdo_pgsql: 5.4.16
        Installing php5-pgsql: 5.4.16

The installation will require 206 kB more space

19 kB to be downloaded

Proceed with installing packages [y/N]: y

The GD library

This provides graphical support. Again you see I explicity tell pkg which version (5.4.16) I require. This installs quite a few more dependencies.

root@groupware:/usr/local/etc # pkg install php5-gd-5.4.16
Updating repository catalogue
The following 22 packages will be installed:

        Installing xproto: 7.0.24
        Installing xextproto: 7.2.1
        Installing printproto: 1.0.5
        Installing libXdmcp: 1.1.1
        Installing libXau: 1.0.8
        Installing libpthread-stubs: 0.3_3
        Installing kbproto: 1.0.6
        Installing libICE: 1.0.8,1
        Installing freetype2: 2.4.12_1
        Installing png: 1.5.16
        Installing jpeg: 8_4
        Installing libxcb: 1.9.1
        Installing libX11: 1.6.0,1
        Installing libSM: 1.2.1,1
        Installing libXt: 1.1.4,1
        Installing libXext: 1.3.2,1
        Installing libXp: 1.0.2,1
        Installing libXmu: 1.1.1,1
        Installing libXpm: 3.5.10
        Installing libXaw: 1.0.11,2
        Installing t1lib: 5.1.2_2,1
        Installing php5-gd: 5.4.16

The installation will require 25 MB more space

118 kB to be downloaded

Proceed with installing packages [y/N]: y

The mbstring library

This is required for multi byte strings. See http://www.php.net/mbstring for more information.

root@groupware:/usr/local/etc # pkg install php5-mbstring-5.4.16
Updating repository catalogue
The following 2 packages will be installed:

        Installing oniguruma: 4.7.1
        Installing php5-mbstring: 5.4.16

The installation will require 4 MB more space

717 kB to be downloaded

Proceed with installing packages [y/N]:

If you use the mbstring functionality, you will also need to alter the mbstring.func_overload = 7 line in php.ini.

The SQLite libary

The configuration checker script reported that this is needed by the calendar function, so I installed it.

root@groupware:/usr/local/etc # pkg install php5-pdo_sqlite-5.4.16
Updating repository catalogue
The following 1 packages will be installed:

        Installing php5-pdo_sqlite: 5.4.16

The installation will require 41 kB more space

15 kB to be downloaded

Proceed with installing packages [y/N]:

Other PHP plugins

If you have a different backend, then you will see from the configuration checker what packages you need to install. Remember to make sure you install the correct version

Other Dependencies

The tnef (or ytnef) utilies

After installation, I found that the configuration checker wasn’t finding the tnef utility. This was installed as part of the intial eGroupware installation, and the tnef utility was placed in /usr/local/bin. However, the configuration checker script explicitly looks in /usr/bin and then uses the which command to locate it. For some reason this wasn’t picking up the file in the /usr/local/bin location – probably a path search problem. Taking the lazy option and rather than alter the configuration script I just used the ln command to make the error go away.

root@groupware:/usr/local/etc # ln /usr/local/bin/tnef /usr/bin/tnef

Aspell: Spelling checker

This is used to perform the spelling checks in the various dialog boxes. This is defined in the configuration screen of eGroupware, so you can change the command here to point to /usr/local/bin/aspell once you’ve logged in to eGroupware as an administrator.

root@groupware:/usr/local/etc # pkg install aspell

Zip: Compression

Again the configuration checker complained about this, so a quick install later..

root@groupware:/usr/local/etc #  pkg install zip

JPGraph support

This is used to to produce GANTT charts in the project management functions. It is another web application which is placed in /usr/local/share/jpgraph. After installing it, the configuration checker continued to throw an error, but my quick checks in eGroupware showed GANNT charts being generated correctly. As I don’t use GANTT charts, I didn’t spend any further time trying to see exactly why the configuration checker generated an error even though the charting was working.

root@egroupware# pkg install jpgraph

Create the apache directive. As before, just adding the file to the /usr/local/etc/apache22/Includes directory means it will be picked up when apache restarts.

Create the file /usr/local/etc/apache22/Includes/jpgraph.conf and add these lines

# jpgraph.conf
   Alias /jpgraph /usr/local/share/jpgraph
   AcceptPathInfo On
   <Directory /usr/local/share/jpgraph>
      AllowOverride None
      Order Allow,Deny
      Allow from all 
   </Directory>

and use

root@groupware:/usr/local/etc #  service apache22 restart

to reload the configuration.

The egroupware configuration checker continued to complain that it couldn’t tell the version of jpgraph, but my quick checks found it executed ok.

The environment

As this installation was migrated from a standalone Linux box, I needed to transfer the files under /var/lib/egroupware to the new system.

As I wrote in at the start, I want to store any uploaded files and backups on the main protected part of the FreeNAS server (the raid-5 disk set). The steps required are:

Create a suitable location on the FreeNAS data partition to hold the files
Copy the files from the old box to this location
Use the FreeNAS web administration to mount the directory under /var/lib/egroupware.
In the eGroupware configartion make sure that file location points to /usr/local/www/egdata/files
In the eGroupware configartion make sure that backup location points to /usr/local/www/egdata/backup

For steps 4 & 5, you could either have a seperate mount for each item, or if your directories on the main drive have the same structure a single mount at the higher leevel would be okay.

Create the eGroupware directories on the main data part of the system. These commands are run from outside the jail.

freenas# cd /mnt/data
freenas# mkdir egroupware
freenas# cd egroupware
freenas# mkdir -p var/lib/egroupware/default/files
freenas# mkdir -p var/lib/egroupware/default/backup

and then mount these into the jail using the gui.

The FreeNAS installation creates a directory /usr/local/www/egdata for these directories. I found that I wasn’t able to use these; when I went into the eGroupware configuration, both of these locations have the warning:

This has to be outside the webservers document-root!!!

next to them. If you don’t want the files stored under /var/lib/ choose another location.

If you are transferring the files from another system, you may need to check and change the file permissions as the UID and GID are likely to be different.

Final Things

Put the production PHP.INI file in place

Remember we originally copied the development version of php.ini into the /usr/local/etc directory. If your system is up and running, it is time to replace the current php.ini file with the production one.

Before copying it over, edit php.ini-production and make sure that the settings you changed before are duplicated here.

The three lines I needed to alter were:

upload_max_filesize = 20M
date.timezone = Europe/London
mbstring.func_overload = 7

Make the changes and then copy the new file over the current php.ini file and restart the Apache service.

[root@groupware /usr/local/etc]# cp php.ini-production php.ini
[root@groupware /usr/local/etc]# service apache22 restart

Other configuration Options

There are a number of other tweaks you can perform if you like. If you’ve other suggestions, please post them below.

Redirect DNS if necessary

My old Linux box had an alias (the same as my http://freedns.afraid.org/ name). This means my smartphones connect to it internally when on my WiFi, or via the normal internet when I’m out and about. I updated my dns server (dnsmasq) so that my freedns name now pointed to the new installation.

Update the dnsmasq hosts file and restart the service.

Force eGroupware to only serve via https

You will need to set the server up to serve HTTPS requests. There are plenty of tutorials on doing this. If you’re using this for a small system, or don’t want to purchase a commercially signed key, then you can use a self signed key. Create this and install it. (I think I used the tutorial on www.linux.com to create mine. There are plenty of other HOWTOs around.)

In order to force Apache to deliver all requests to eGroupware via HTTPS, add these lines to you egroupware.conf file and restart Apache.

<directory /usr/local/www/eg>
     .... other stuff .....
     # redirect all egroupware accesses to https
     RewriteEngine On
     RewriteCond %{HTTPS} off
     RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
     ...other stuff .....
</directory>

Force all accesses to the server to go to the eGroupware system

As this server is only designed for a single purpose, I want to automatically to go to the login screen (ie. http://myserver.com will automatically go to https://myserver.com/eg).

I just need to add the following lines to the default directories in the httpd.conf file

<Directory "/usr/local/www/apache22/data">
    .... default stuff .....
    RewriteEngine on
    RewriteRule .* https://%{HTTP_HOST}/shop/ [R,L]
</Directory>

Explicitly add php options to eGroupware

Strictly speaking, I don’t think I really need to do this as this server is only configured to serve the eGroupware system, however as I migrated from a Linux system that was serving several applications, I just migrated all the settings over as well.


<Directory /usr/local/www/eg>
  Options FollowSymLinks ExecCGI
  AllowOverride None
  Order allow,deny
  Allow from all
  DirectoryIndex index.html index.php
  AddHandler cgi-script .cgi
  AddDefaultCharset Off
  php_flag file_uploads on
  php_flag log_errors on
  php_flag magic_quotes_gpc off
  php_flag magic_quotes_runtime off
  php_flag register_globals off
  php_flag short_open_tag on
  php_flag track_vars on
  php_flag display_errors off
  # E_ALL & ~E_NOTICE & ~E_STRICT = 8191 - 8 - 2048 = 6135
  php_value error_reporting 6135
  php_value max_execution_time 90
  php_admin_value mbstring.func_overload 7
  php_value memory_limit 128M
  php_value session.gc_maxlifetime 14400
  php_value include_path .:/usr/local/share/php5/PEAR:/etc/php5:/usr/local/etc/php5:/usr/local/etc:/usr/local/share/pear
  php_admin_value open_basedir /usr/local/www/eg:/var/lib/egroupware:/tmp:/usr/local/share/pear:/usr/local/etc/php5:/usr/local/bin/zip:/usr/local/share/jpgraph:/usr/bin/tnef:/usr/local/bin/aspell:/usr/share/fonts:/usr/local/share/pear
  php_value upload_max_filesize 64M
  php_admin_value upload_tmp_dir /tmp
  php_value post_max_size 65M
  php_value max_input_vars 3000

  <Files ~ "\.inc\.php$">
    Order allow,deny
    Deny from all
  </Files>

   # redirect all egroupware accesses to https

   RewriteEngine On
   RewriteCond %{HTTPS} off
   RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}

</Directory>

I needed to modify the include_path line because the Linux install had most things under /usr/ and FreeNAS places them under /usr/local.

And Finally

The process was actually quite straightforward in the end. It took longer to write this up, than actually do it. The only gotcha that got me was the fact that the files and backups needed to be outside the www root directory. If I’d actually read teh configuration screen carefully the first time, then I wouldn’t have tried to move the location from /var in teh first place.

I hope this helps someone else.

Lonbil Blog

Another WordPress site

Installing eGroupware on FreeNAS

Installing eGroupware on FreeNAS

Background

Current System

Proposed System

Installing eGroupware on FreeNAS

Build a jail to hold the system

PHP setup

Configuring the `php.ini` File

Configure PHP environment

The GD library

The mbstring library

The SQLite libary

Other PHP plugins

Other Dependencies

The tnef (or ytnef) utilies

Aspell: Spelling checker

Zip: Compression

JPGraph support

The environment

Final Things

Put the production PHP.INI file in place

Other configuration Options

Redirect DNS if necessary

Force eGroupware to only serve via https

Force all accesses to the server to go to the eGroupware system

Explicitly add php options to eGroupware

And Finally

Leave a Reply Cancel reply

Installing eGroupware on FreeNAS

Background

Current System

Proposed System

Installing eGroupware on FreeNAS

Build a jail to hold the system

PHP setup

Configuring the php.ini File

Configure PHP environment

The GD library

The mbstring library

The SQLite libary

Other PHP plugins

Other Dependencies

The tnef (or ytnef) utilies

Aspell: Spelling checker

Zip: Compression

JPGraph support

The environment

Final Things

Put the production PHP.INI file in place

Other configuration Options

Redirect DNS if necessary

Force eGroupware to only serve via https

Force all accesses to the server to go to the eGroupware system

Explicitly add php options to eGroupware

And Finally

Leave a Reply Cancel reply

Configuring the `php.ini` File