Helper packages

sudo apt-get install wv xpdf-utils unrtf unzip links
sudo cpan MP3::Tag

Install source

svn co https://repo.socialtext.net:8999/svn/socialtext/trunk socialtext
cd socialtext/nlw
./configure --socialtext-open 1 --apache-proxy 0 --force-ssl-login 1
make
sudo bash
make install
update-rc.d -f apache-perl remove
update-rc.d st-apache defaults
update-rc.d ceqlotron defaults
/etc/init.d/st-apache start
/etc/init.d/ceqlotron start

Update existing checkout

cd socaialtext
svn update
cd nlw
./configure --socialtext-open 1 --apache-proxy 0 --force-ssl-login 1
make
make test
sudo make install
sudo /etc/init.d/st-apache stop
sudo /etc/init.d/ceqlotron restart
sudo /etc/init.d/st-apache start

Add new admin user

sudo -u www-data st-admin create-user --email dpavlin@rot13.org --password wikidream \
  --first-name Dobrica --last-name Pavlinusic
sudo -u www-data st-admin add-workspace-admin --email dpavlin@rot13.org

Configuring mailer

postfix

Install and configure postfix for mail delivery

apt-get install postfix
vi /etc/postfix/main

Important lines are following:

alias_maps = hash:/etc/aliases, hash:/etc/aliases.deliver
alias_database = hash:/etc/aliases, hash:/etc/aliases.deliver

They add /etc/aliases.deliver (which SocialText generates with names of wiki workspaces) to configuration.

Next, we need to create /etc/aliases.deliver.db which is binary version of database needed for postfix. It's extremly important that aliases.deliver file is owned by www-data because postfix picks user which will do e-mail delivery based on owner of aliases file. If your owner of /var/www/socialtext is some other user than www-data you will have to modify following command appropriately:

# make www-data owner of file
chown www-data:root /etc/aliases.deliver
# allow root group to write in /etc/
chmod g+w /etc/
# create /etc/aliases.deliver.db
sudo postalias /etc/aliases.deliver

Now restart postfix as root user

/etc/init.d/postfix restart

crontab

Add following to /etc/crontab to refresh aliases database for postfix regularly:

*/10 *  * * *   root    postalias /etc/aliases.deliver

Handling e-mail errors

sudo tail /var/log/mail.log | grep st-admin

dsn=5.3.0, status=bounced (Command died with status 13: "/usr/local/bin/st-admin deliver-email --workspace bio". Command output: open nlw-stats.log: Permission denied at /usr/local/share/perl/5.8.8/Socialtext/Statistics.pm line 103. END failed--call queue aborted. )

This problem is reported on socialtext-devel list, but no response so far.

# sudo vi +24 /usr/local/share/perl/5.8.8/Socialtext/Statistics.pm
Readonly my $LOG_NAME => 'nlw-stats.log';
Readonly my $LOG_PATH => $ENV{APACHE_LOG_DIR}
    ? "$ENV{APACHE_LOG_DIR}/$LOG_NAME"       
    : "/tmp/$LOG_NAME";

Customize template

Remove "Did you know?" box from dashboard

sudo vi /usr/share/nlw/template/view/homepage

Or from your socialtext/nlw checkout (so that make install will install correct one):

vi share/template/view/homepage

Fix RSS feed errors

If you are using {fetchrss http://blog.rot13.org/index.xml} and having problems with RSS feeds, try to re-installing two perl modules:

sudo cpan XML::RSS XML::Atom

New skin (CSS design) creation

cd /usr/share/nlw/css/
cp -r st rot13
st-admin set-workspace-config --workspace rot13 skin_name rot13
vi rot13/screen.css

Change e-mail address of workspace

This configuration change will feed responses to e-mails generated by wiki back into wiki. You might not want to do that! :-)

st-admin set-workspace-config --workspace rot13 \
  email_notification_from_address '"random unstructured stuff" <rot13@wiki.rot13.org>'

Access simple version of page

Every SocialText wiki has a lite version available at http://wiki.example.com/lite/page/:workspace/

For this wiki it's http://saturn.ffzg.hr/lite/page/rot13

Keep local changes in SVN

It's important to save local modifications, because next make install will overwrite your changes in /usr/share/nlw. One possibility is to do overlay svn checout over /usr/share/nlw and than svn add and svn commit every change:

cd /usr/share
svn co file:///data/st-custom/share nlw.svn
cd nlw.svn
find . | cpio -pdu ../nlw/
rm -Rf nlw.svn
cd nlw
svn info

Update to trunk version

It seems that new subversion trunk available at https://repo.socialtext.net:8999/svn/socialtext/trunk/ has problem with upgrade of database. If you get message like this:

ALTER TABLE "UserWorkspaceRole" ADD CONSTRAINT fk_2d35adae0767c6ef9bd03ed923bd2380 FOREIGN KEY ( "user_id" ) REFERENCES "UserId" ("system_unique_id") ON DELETE CASCADE
DBD::Pg::st execute failed: ERROR:  insert or update on table "UserEmailConfirmation" violates foreign key constraint "fk_777ad60e2bff785f8ff5ece0f3fc95c8"
DETAIL:  Key (user_id)=(6) is not present in table "UserId".

SQL: ALTER TABLE "UserEmailConfirmation" ADD CONSTRAINT fk_777ad60e2bff785f8ff5ece0f3fc95c8 FOREIGN KEY ( "user_id" ) REFERENCES "UserId" ("system_unique_id") ON DELETE CASCADE

Trace begun at /usr/local/share/perl/5.8.8/Alzabo/Driver.pm line 234
Alzabo::Driver::_prepare_and_execute(undef, 'sql', 'ALTER TABLE "UserEmailConfirmation" ADD CONSTRAINT fk_777ad60e2bff785f8ff5ece0f3fc95c8 FOREIGN KEY ( "user_id" ) REFERENCES "UserId" ("system_unique_id") ON DELETE CASCADE') called at /usr/local/share/perl/5.8.8/Alzabo/Driver.pm line 249
Alzabo::Driver::do('Alzabo::Driver::PostgreSQL=HASH(0x8ae5074)', 'sql', 'ALTER TABLE "UserEmailConfirmation" ADD CONSTRAINT fk_777ad60e2bff785f8ff5ece0f3fc95c8 FOREIGN KEY ( "user_id" ) REFERENCES "UserId" ("system_unique_id") ON DELETE CASCADE') called at /usr/local/share/perl/5.8.8/Alzabo/Create/Schema.pm line 833
Alzabo::Create::Schema::sync_backend('Alzabo::Create::Schema=HASH(0x8ae4ff0)', 'password', undef, 'user', 'nlw', 'schema_name', 'NLW', 'port', undef, 'host', '') called at bin/st-db line 140
main::sync('Alzabo::Create::Schema=HASH(0x8ae4ff0)') called at bin/st-db line 67
main::__ANON__ at bin/st-db line 95
eval {...} at bin/st-db line 95
main::_repeat_ignoring_other_access('CODE(0x8ccac00)') called at bin/st-db line 67
make: *** [schema] Error 255

You will need to do manual update using following procedure:

sudo -u postgres dropdb NLW
sudo -u postgres createdb --owner nlw --encoding UTF8 NLW
sudo -u postgres psql NLW nlw < /tmp/NLW-dump.1175010986.sql
sudo -u postgres psql NLW nlw < socialtext/nlw/share/migrations/1-auth-refactor/migration.sql

Now, re-run make install

Configure sane resource usage

Since SocialText wiki is designed to run on dedicated box, it's resource requiements are not for faint-hearted users. However, if you are installing it on machine with constraint hardware (or virtual machine) you might want to decrease number of apache-perl server which are created on startup and kept running. Each apache child takes about 80Mb of RAM, so lowering number of children will have beneficial effect on your memory usage.

If you open /etc/apache-perl/st-httpd.conf you will see comment that describes command used for generating this configuration. So, let's edit command limits, re-create config and restart apache:

vi +485 dev-bin/gen-config
dev-bin/gen-config --sitewide --apache-proxy=0 --hostname=saturn.ffzg.hr
/etc/init.d/st-apache reload