Stephen
Ierodiaconou

Installing Teambox: A Full Guide For Debian and Apache

Copyright Stephen Ierodiaconou 2010

Teambox is an excellent project management system. It follows a ”social” logic, introducing status updates, discussions and collaborative working to create a sort of tasks/wiki/timetracking/twitter mix. It has ”external” user accounts allowing clients limited access to projects to get status updates/share files/join discussions etc. It is constant flux with new features appearing regularly. In my opinion, though it sorely misses a few key features (such as a way to organise uploads), it is the best project management web app I have tried to date.

Installing Teambox is relatively straight forward, but I ran into a few little issues here and there so, after working them out, here is what I did.

The following instructions are to install from the latest Community Edition on Github and include installing search and imagemagick dependancies.

To build Teambox there are a number of critical dependancies (gcc and the like) and so you will actually need around +200Mb disk space to install these alone. It is also important to note that it is a large Rails app and requires 100-200+Mb free memory to run.

This document is based on information from a number of sources, but most importantly:

• Installing on Ubuntu
• Installing Locally
• Configure Search
• Configure Email

If you find any errors or anything else of note, email me at stephen@flat53.com.

NOTE: Teambox is not at all designed to live in a subdirectory of a domain, e.g. http://www.my.com/teambox (I tried it) Hence it is recommended to install it in its own (sub)domain, e.g. http://teambox.my.com. This makes configuring the Apache webserver alot easier. If you really must install it in a subfolder there are some instructions at the end of this entry.

Assumptions

The following docs assume you are a normal user user unless specified that your should elevate yourself to superuser (with su). Where elevating your privileges be very very careful!

This document assumes you have a Debian install with Apache2 and MySQL already installed. Also ensure you have wget (apt-get install wget)

Getting ready

We are going to install Teambox for our domain teambox.my.com in location /home/user/sites/teambox.my.com.

First we create the necessary directories

cd ~/sites
mkdir teambox.my.com
mkdir teambox.my.com/logs

The logs folder will be used for the error and access logs of the site if desired.

Installing dependancies

There are a number of dependancies necessary to build Teambox. You may find that many can be removed after building Teambox, Sphinx and so on. Keep in mind that all these dependancies have quite a large space requirement. If you are scared by the amount of space, dont include imagemagick but then thumbnails will not generate for your image uploads.

Run the following as su:

apt-get update
apt-get install \
     build-essential ruby ruby-dev irb libmysqlclient15-dev sqlite3 libsqlite3-dev \
     libcurl4-openssl-dev libopenssl-ruby libpcre3-dev libxml2-dev libxslt-dev \
     libreadline5-dev apache2 apache2-prefork-dev libapr1-dev git-core imagemagick

Now exit su (by typing exit) and download the other deps: RubyGems and Sphinx. The information below is for the current version numbers. To get the latest ones go to the respective sites and find out the latest download file path and change the commands accordingly. NOTE: if you have rubygems installed you need only update to the latest and can skip its installation.

cd ~/
wget http://www.sphinxsearch.com/downloads/sphinx-0.9.9.tar.gz
wget http://production.cf.rubygems.org/rubygems/rubygems-1.3.7.tgz
tar -C sphinx -zxvf sphinx-0.9.9.tar.gz
tar -C rubygems -zxvf rubygems-1.3.7.tgz
cd rubygems

Now change to su

ruby setup.rb
ln -s /usr/bin/gem1.8 /usr/bin/gem

Now you have rubygems you can install the bundler gem

gem install bundler

Now exit su (by typing exit) and then build Sphinx by doing the following,

cd sphinx 
./configure
make

then as su

make install

Now exit su (by typing exit) and assuming all went to plan clean up your home by

cd ~/
rm sphinx-0.9.9.tar.gz rubygems-1.3.7.tgz
rm -rf sphinx
rm -rf rubygems

Note, you may wish to install Ruby Enterprise Edition for a better performance Ruby, but I have not done this yet.

Building Teambox

The latest code to Teambox is on Github at their repository in the master branch.

To get a copy of it onto your local machine do:

cd ~/sites/teambox.my.com
git clone git://github.com/teambox/teambox.git

This creates a new directory teambox containing the latest source. To prepare Teambox do:

cd teambox
bundle install

Configure Teambox

In the following commands use your favourite editor to modify the configuration files. I use nano (Ctrl-O to save Ctrl-X to exit) First make sure you are out of su more (type exit if you are superuser)

First we will create a new database a teambox user in MySQL. In the following MySQL commands (prepended by ‘>’) make sure you change at least the password for the teambox user.

mysql -u root -p
(your MySQL root password)
> create database teamboxDB;
> grant usage on *.* to teambox@localhost identified by 'PASSWORD';
> grant all privileges on teamboxDB.* to teambox@localhost;
> exit

Now we need to configure the database config file (you should be in the teambox/ directory, if not cd ~/sites/teambox.my.com/teambox )

cp config/database.example.yml config/database.yml
nano config/database.yml

Find the production settings and set your mysql username, password and database name.

production:
  adapter: mysql
  host: localhost
  username: teambox
  password: PASSWORD
  database: teamboxDB

Now save and exit (you can also configure the development and test environments if you wish to use these at some point, for example to test new versions without risking your database).

Now enter the following to build the initial database contents for teambox. This builds the production enviroment database, change this to development or test for other environments as necessary.

rake db:create db:schema:load RAILS_ENV=production

The config/teambox.yml contains general settings for your teambox install.

nano config/teambox.yml

The following options should be set if desired:

set this to your domain name

app_domain: teambox.my.com

set this to true if you have SSL setup on your system, otherwise leave it false

secure_logins: true

set this to true if you want tasks to have time tracking options. This feature is a bit immature but I enable it.

allow_time_tracking: true

Since we are installing search set this to true

allow_search: true

Set this to your time zone, e.g. GMT

time_zone: GMT

We will also configure the email sending and receive accounts here. The sending settings (the account used to send invites/updates/activation requests etc) are in smtp_settings (you need SMTP). This can either be an account on your local machine or you can use another provider like GMail

For GMail modify the settings as follows:

smtp_settings:
  :domain:         gmail.com         # the domain your emails will come from
  :address:        smtp.gmail.com  # SMTP server used to send emails
  :port:           587
  :authentication: :plain
  :user_name:      username
  :password:       password
  :enable_starttls_auto: true

Note if you are seeing Net::SMTPSyntaxError errors in ~/sites/teambox.my.com/teambox/log/production.log when you try the server, modify the following setting to true (see the comment)

# Set to true if you have Net::SMTPSyntaxError errors when sending email.
# Rails has sometimes a problem when sending email from "Name <address@host.com>".
# If you are having problems sending email and your host is correctly configured,
# try setting safe_from to true. You may need to create a user account for no-reply@yourapp.com
:safe_from: false

Now personally I wanted to use an account on my own server. However there seems to be a problem with Ruby ActionMailer and TLS. I always get OpenSSL::SSL::SSLError (hostname was not match with the server certificate): errors even though my Cert and SSL setup if definitely fine. On the net I found suggestions of disabling TLS (but dont want to do that) so instead I traced the error to

/usr/lib/ruby/1.8/openssl/ssl.rb:123:in `post_connection_check'

and simply commented out the validity check. A HACK I know, but what else can I do? If you know please contact me!

To setup the ability for users to reply to messages sent to their inbox by Teambox, you must configure teambox to monitor an email account and setup a catch-all for teambox. First I setup an email account on the server, teambox@teambox.my.com and then create a catch all @teambox.my.com to forward to this new account.

Then open the configuration file (if you dont have it open already)

nano config/teambox.yml

and find the option allow_incoming_email and set it to true

allow_incoming_email: true

Next find the section incoming_email_settings to configure the mail account options. I could not get IMAP to work but POP works fine

incoming_email_settings:
  :type:      POP
  :address:   mail.my.com
  :user_name: teambox
  :password:  PASSWORD

Now when a message is sent by teambox to a user, rather than being from no-reply it comes from an ‘email address’ which identifies the specifics of the comment. When the user replies to this email, the catch-all forwards the email to teambox@teambox.my.com.

Restart apache as su.

For teambox to know about new emails, there are a number of approaches, however I chose to simply setup a cron-job to check the mail box every 5 minutes. Copy in the following and edit the path to be your path:

PATH=/usr/local/bin:/usr/bin:/bin
SHELL=/bin/bash
*/5 * * * * cd /home/user/sites/teambox.my.net/teambox && RAILS_ENV=production rake mail:inbox >/dev/null 2>&1

Test Teambox

Now test your new Teambox install! Run the next command as normal user in the teambox directory

script/server -e production

This will start the server. Navigate your web browser to http://teambox.my.com:3000 and check that the teambox setup wizard shows. Now return to your terminal and Ctrl-C to exit the server. We don’t need an instance running as after we setup Apache it will handle the this.

If there are any problems check ~/sites/teambox.my.com/teambox/log/production.log. This should indicate what the problem is.

Configure Apache

The following setup must be run as su (superuser) so do su first.

Passenger allows Rails apps to be run under Apache.

gem install passenger
passenger-install-apache2-module

the above command outputs a bunch of information, and specifically you are interested in the lines that look like:

LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-2.2.15/ext/apache2/mod_passenger.so

and

PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.2.15
PassengerRuby /usr/bin/ruby1.8

Now create the passenger mod with

nano /etc/apache2/mods-available/passenger.load

and paste in the LoadModule line, e.g.

LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-2.2.15/ext/apache2/mod_passenger.so 

Save and exit and then run the following to add the configuration for passenger:

nano /etc/apache2/mods-available/passenger.conf

Paste in the PassengerRoot and PassengerRuby, e.g.:

PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.2.15
PassengerRuby /usr/bin/ruby1.8

Now we enable our new module:

a2enmod passenger

Run the following to make sure deflate module is enabled too:

a2enmod deflate

Now to configure the vhosts file for apache.

nano /etc/apache2/sites-available/teambox.my.com

The add the following (or add the settings to the *:80 section if you already have one):

<VirtualHost *:80>
    Options +Indexes
    ServerAdmin teamboxadmin@my.com
    ServerName teambox.my.com
    SetOutputFilter DEFLATE
    # file-types indicated will not be compressed
    SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png|rar|zip|pdf)$ no-gzip dont-vary
    <IfModule mod_headers.c>
        Header append Vary User-Agent
    </IfModule>
    DocumentRoot /home/user/sites/teambox.my.com/teambox/public
    #ErrorLog /home/user/sites/teambox.my.com/logs/error.log
    #CustomLog /home/user/sites/teambox.my.com/logs/access.log combined
    <Directory /home/user/sites/teambox.my.com/teambox/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Order allow,deny
        Allow from all
        Options -MultiViews
    </Directory>
    RailsEnv production
 </VirtualHost> 

If you have SSL setup copy the above settings into your <VirtualHost *:443> section for the domain too.

Note you should also add any other configurations to your vhosts file as you need.

Now enable the site

a2ensite teambox.my.com

the restart apache (or start if its not running already with the start command):

/etc/init.d/apache2 restart

If there are any errors, check /var/log/apache2/error.log and edit your /etc/apache2/sites-available/teambox.my.com file and uncomment (remove the # from in front of ErrorLog) then try another access and check /home/user/sites/teambox.my.com/logs/error.log.

Create your Admin account

Now go to http://teambox.my.com/ and you will see some on screen instructions. These will guide you through creating your first user account (who is also a site wide admin) and your first project. Note that the system sends a confirmation email to allow signup so you must have correctly configured your email before.

Create Search Index

First we must create the initial search index and start the thinking_sphinx service:

cd ~/sites/teambox.my.com/teambox
rake ts:index RAILS_ENV=production
rake ts:start RAILS_ENV=production

Now setup a Cronjob to update the index periodically. The instructions on Github didn’t work for me so I did this instead: (Note this a root user job, you may want to modify the permissions of the folders of the Sphinx indexer and run the job as a lower permissions user, but I don’t have the specifics on this)

Do as su

crontab -e

then copy in the following and edit the path to be your path:

PATH=/usr/local/bin:/usr/bin:/bin
SHELL=/bin/bash
*/10 * * * * cd /home/user/sites/teambox.my.net/teambox && RAILS_ENV=production rake ts:reindex >/dev/null 2>&1

This sets the indexer to run every 10 minutes for the production environment and sends the job output to /dev/null. The PATH is needed to ensure that the indexer can be found. If your indexer is in some other location (use which indexer to find out) then modify the PATH command to include your path.

Disable Logging

If everything is working fine do

cd ~/sites/teambox.my.com/teambox
nano config/environments/production.rb

and add the line (or edit the config.logger line to nil)

config.logger = nil

This will prevent your server filling with log files!

Appendix (clear the database, clearing the cache, updating to the latest version and more)

Installing in a Subdirectory

If you really must install in a subdirectory here are the options you need. Assuming Teambox is built in a folder /home/user/sites/my.com/teambox and your DocumentRoot is set to /home/user/sites/my.com/public_html

First your DocumentRoot should point to your site already, so make a symlink to the teambox/public folder in your document root called say teambox

cd ~/sites/my.com/public_html
ln -s ../teambox/public teambox

The as superuser ensure mod rewrite is on:

a2enmod rewrite

the modify your sites vhosts file, e.g. /etc/apache2/site-available/my.com, and add the following (modify the Directory to the name of your folder):

RewriteEngine On
RewriteRule ^/(users|sounds|images|projects|assets)(/.*|$) /teambox/$1$2
RailsBaseUri /teambox
RailsEnv production
<Directory /teambox>
    Options FollowSymLinks
    AllowOverride All
    Order allow,deny
    Allow from all
    Options +Indexes
    Options -MultiViews
</Directory>

Now restart apache.

/etc/init.d/apache2 restart

Updating

To update your Teambox to the latest git version, do the following

cd ~/sites/teambox.my.com/teambox 
git stash # this saves your changes to files in a stash
git pull  # this gets the new teambox code
bundle install # this updates the gems
git stash pop # now we can restore your configuration changes
rake db:migrate RAILS_ENV=production
rm public/sprockets.js # removes cached version of JavaScript libraries
touch tmp/restart

This snippet is from here.

Leaky Leaky SSL

If you have SSL setup you may notice the saslauthd process slowly eating all your system memory. If this is happening to you set THREADS=0 in `/etc/default/saslauthd.conf’ . This seems to fix the leak but at the risk of a performance hit, though I have read around on the net that the perf hit is small.

Clear the Database

If you want to empty the database to start from scratch you need simply delete and create a new database in mysql:

mysql -uroot -p
> drop database teambox;
> create database teambox;
> grant all privileges on teamboxDB.* to teambox@localhost;

then re-run:

cd ~/sites/teambox.my.com/teambox
rake db:create db:schema:load RAILS_ENV=production

Clear the site cache

In the directory tmp under teambox is a directory where cached views are stored. If you say clear the database you should also clear the caches to prevent stale data from being displayed.

cd ~/sites/teambox.my.com/teambox/tmp
rm -rf cache/*