NOTE: I am currently working on an update to this guide to reflect some changes in the installation process that have been introduced recently in svn. Until this notice goes away, consider this document in flux. If you want to view the document as it applies to the latest release, 2.9.5.2, look at revision 16.

This guide should be sufficient to walk one though an installation of Socialtext Open on 64-bit Ubuntu 6.06 (Dapper). I started with a fully updated "server" install from the "alternate install" disc, but I don't see any reason that this wouldn't work with a "normal" or 32-bit installation. It may even work on other releases, but I haven't tested that. All of this is based on my first-hand experience and "my way" of doing things. There may be places where you can do things differently to get the same or similar results. If you "know what I mean" but would rather do it differently, do so. For instance, I prefer to use aptitude rather than apt-get to do my installations.

Note: Much of this material is presented in the install docs that come with Socialtext Open, but I include it here for completeness. Also, this guide does not cover any of the email integration capabilities of socialtext as I have not yet gotten those working myself. They will be added ASAP!

Preparations and Dependencies

Socialtext Open has a lot of dependencies, and getting those sussed out is the hardest part of the installation.

1- Login to your fully updated Dapper box as a user with admin privileges. I prefer to switch to a root shell at this point by executing:

sudo bash

However, it is more "correct" to stay in a normal user shell and sudo each command that requires root access. If you choose to work that way, add sudo to the beginning of the command examples I give as is appropriate.

2- Make sure you have Universe enabled for apt and add the Socialtext package repository for getting the Perl packages. Do this by making sure you have lines like the following in your /etc/apt/sources.list:

#Main repo, with universe enabled
deb http://us.archive.ubuntu.com/ubuntu/ dapper main restricted universe
deb-src http://us.archive.ubuntu.com/ubuntu/ dapper main restricted universe

#Updates repo, with universe enabled
deb http://us.archive.ubuntu.com/ubuntu/ dapper-updates main restricted universe
deb-src http://us.archive.ubuntu.com/ubuntu/ dapper-updates main restricted universe

#Security updates repo, with universe enabled
deb http://security.ubuntu.com/ubuntu dapper-security main restricted universe
deb-src http://security.ubuntu.com/ubuntu dapper-security main restricted universe

#Socialtext repo for perl deps
deb http://open.socialtext.net/apt socialtext-open main

3- Next, we need to get the Socialtext gpg keys so we can use their repository. It will complain when you install socialtext-keyring that it is untrusted. That is normal, we need to install the keyring before the system will trust packages from this repo.

aptitude update
aptitude install socialtext-keyring
aptitude update

4- There are some useful files in the Socialtext Open distribution that will make the next steps easier, so if you haven't already gotten the latest package (version 2.9.5.2 at the time of this writing) you can get it from SourceForge at http://sourceforge.net/projects/socialtext/. Once you have the tarball, copy it to a working directory of your choice, and extract it. If you sudo'd into a bash shell, drop back to your normal user for this step so the extracted files will be owned by you:

tar -zxvf Socialtext-Open-2.9.5.2.tar.gz

5- Now we need to install some system dependencies. The easiest way to do this is to leverage the package list that is included in the tarball. So, from your working directory:

aptitude install `cat $SOURCE_DIR/build/pkg-lists/dapper`

$SOURCE_DIR above will correspond to the base directory that was extracted from the tarball you downloaded previously. This will take awhile on a base installation. Go get a coffee or something.

NOTE The installation process will complain about apache-perl needing to be reconfigured and that your version of postgres (7.4) is obsolete. Don't worry about this right now. Apache-perl should get properly reconfigured at the end of the installation, and postgres 7.4 works fine. Furthermore, I tried getting this going with 8.1 and it didn't work. I don't know why at this point.

6- Now we can install some extra optional packages which make Socialtext Open a little more featureful:

aptitude install lynx catdoc wv xpdf-utils gs-common unrtf unzip

7- Now install the st-perl-deps package. NOTE: If you get an error about an unresolvable dependency at this point, it is because you haven't enabled Universe on your Security repo. Revisit step 2.

aptitude install st-perl-deps

Again, this will take awhile, especially if you are on a slower connection. It's downloading about 1.2 million little Perl packages. :D I'm sure glad I don't have to do this bit by hand... Go get another coffee or something.

NOTE - If you've read the Socialtext Open install docs, or tried a stoss installation already, you know that the ./configure tool will run cpan and try to install all these deps from there. I have yet to see that work, it gets caught in a loop with test failures. I have not dove into this problem, but I suspect there is a package in there that does not correctly define all it's dependencies. At any rate, using the stoss repo is what got me a working install.

8- We're almost done installing dependencies. There are a few more Perl modules we need to install by hand to allow everything to work smoothly. You'll need to have the CPAN installed and configured. The CPAN module is standard with Perl, but may not have been configured for your system. I'm not going to detail that here, but if you don't already have it configured, it's generally safe to stick with the defaults for any question it might ask you:

cpan install Test::Output Test::Simple Test::Base Test::Pod Test::Pod::Coverage MP3::Tag CSS

Strictly speaking MP3::Tag is optional. Feel free to omit it. CPAN will ask if you want to install other modules with are required by these. Say yes.

Configure Postgres

Socialtext Open uses PostgreSQL to store a number of pieces of information. At this point we need to do some configuration of postgres to make stuff work. This content is more or less lifted verbatim from INSTALL.postgres in the tarball.

1- First we need to make postgres trust connections originating from the local machine so that the apache-perl process can access it. There is likely a more secure way to do this, but I don't know it. Insert the following lines into /etc/postgresql/7.4/main/pg_hba.conf:

local   template1   nlw                      trust
local   NLW         nlw                      trust

Make sure they go above the line that looks like:

local   all         all                      ident sameuser

If you don't, stuff will break.

2- Restart postgres:

/etc/init.d/postgresql-7.4 restart

3- Create the users and databases you need:

sudo -u postgres createuser nlw
sudo -u postgres createdb -O nlw NLW
sudo -u postgres createuser $USER
sudo -u postgres createdb -O $USER NLW_$USER_testing

Allow the nlw user to create databases, but not users. Replace the $USER above with the username of whatever user you are planning on running "make test" with. In my case, I replaced it with "root".

Install Socialtext Open

1- We're finally ready to do the actual installation of Socialtext Open. It is wise to drop out of the root account at this point and run ./configure, make, and make test as a normal user. This is both for security and so that tests don't pass when they shouldn't doe to permissions and the like. Once you are back as a normal user, run these commands in succession:

./configure --hostname=$IP --support-address=email@somedomain --server-admin=email@somedomain
make
make test

 and then as root:

make install

Note: The make test step seems to fail right now, but the installation seems to work anyway.

Replace the email addresses and $IP in the first command with values that are appropriate for your site. $IP may be a fully qualified domain name and not an IP address, if that is appropriate for your setup. The ./configure command will want to install a few more dependencies from CPAN, so let it. When it asks about options for Alzabo, leave the "alzabo root" as /var/lib/alzabo, say "no" to the MySQL driver, "yes" to the postgres driver, and "no" to the RDBMS tests. Again, CPAN may ask about dependent modules, so let it get them. The dependency tree for this stuff is deep, so you'll need to pay attention here and approve a number of dependencies. Hopefully everything went correctly. You're past the hard part.

2- Now we need to get your initial users setup and associate them with a workspace. This will serve as your main "admin user" to create other workspaces and invite users.

sudo -u www-data st-admin create-user --email email@somedomain --password somepass --first-name Quentin --last-name Hartman
sudo -u www-data st-admin add-workspace-admin --email email@somedomain --workspace help

3- There seems to be a flaw in the current install process wherein one directory that is needed for ceqlotron to work is not created. To do that by hand and allow ceqlotron to work, do:

mkdir /var/run/socialtext
chown www-data:www-data /var/run/socialtext

4- Now we can actually get socialtext started. In order for this to work though, we first need to stop the perl-apache process that automatically gets started when it is installed. In fact, let's disable it entirely and set socialtext to start automatically at bootup

update-rc.d -f perl-apache remove
/etc/init.d/perl-apache stop
update-rc.d st-apache defaults
update-rc.d ceqlotron defaults
/etc/init.d/st-apache start
/etc/init.d/ceqlotron start

At this point you should be able to connect to your Socialtext installation and login as the user you created previously. Congratulations! You're done!

Quentin, this is great. Thanks so much for writing it up. I'm going to look at what I can take from here to update in the docs.

contributed by Andy Lester on Feb 9, 2007 2:07pm

This walkthrough worked perfectly also on a Ubuntu Feisty Fawn Server (64 bit) install. Thank you Quentin!
I have some problems with images, mails and ST-unplugged as I can see. Will question on user mailing-list.
Bye, Giulio

contributed by Giulio Montevecchi on Apr 30, 2007 4:21am

Hi Folks!

I have a problem during configure since the sistem ask for apache proxy. I use this line to configure:

 ./configure --socialtext-open=1 --apache-proxy=0 --hostname=$IP --support-address=email@somedomain --server-admin=email@somedomain 

Emmanuele

PS. I installed the system with 6.06 LTS 32bit and postgres 8.1 contributed by Emmanuele **Wolf** on Mar 13, 2008 3:43pm