Samizdat Installation
=====================

Required Software
-----------------

You need the following software to run Samizdat: Ruby programming
language environment, Apache web server, PostgreSQL database with
enabled PL/pgSQL procedural language, Ruby/Postgres bindings, Ruby/DBI
interface, and YAML4R library. For better performance, you should run
Samizdat with mod_ruby or FastCGI module. Other recommended modules are:
Ruby/GetText for translation of user interface to different languages,
Ruby algorithm/diff for version comparison, and RedCloth for Textile
hypertext markup.

On Debian GNU/Linux, you can install all that with the following
command:

   apt-get install ruby apache libapache-mod-ruby postgresql libdbd-pg-ruby \
      libyaml-ruby libgettext-ruby1.8 libalgorithm-diff-ruby libredcloth-ruby

To use FastCGI instead of mod_ruby, replace libapache-mod-ruby with
libapache-mod-fastcgi and libfcgi-ruby in the above invocation.

If you are running Debian GNU/Linux 3.0 (woody), you can get backported
packages from http://people.debian.org/~angdraug/. In that case, you
should explicitly specify ruby1.8 and libyaml-ruby1.8 in the above
apt-get invocation.

If you are not using Debian and your system doesn't include these
packages, you can get them from the following URLs:

   http://ruby-lang.org/
   http://httpd.apache.org/
   http://www.modruby.net/
   http://www.postgresql.org/
   http://www.jp.postgresql.org/interfaces/ruby/
   http://ruby-dbi.sourceforge.net/
   http://yaml4r.sf.net/
   http://ponx.s5.xrea.com/hiki/ruby-gettext.html
   http://raa.ruby-lang.org/list.rhtml?name=fcgi
   http://www.whytheluckystiff.net/ruby/redcloth/
   http://www.rubynet.org/mirrors/diff/

If you are using older Ruby 1.6, you should also install StringIO module
from the Ruby Shim library:

   http://raa.ruby-lang.org/list.rhtml?name=shim-ruby16_18

To run optional functions of Samizdat, such as Pingback and regression
test suite, you need more Ruby modules: REXML, XML-RPC, and Test::Unit.
All these modules are included in Ruby 1.8 standard library; on Debian,
you should install librexml-ruby, libxmlrpc-ruby, and libtest-unit-ruby.


PostgreSQL Setup
----------------

Create "samizdat" database and user in PostgreSQL. Run as root:

   su - postgres
   createdb samizdat
   createuser samizdat

If PL/pgSQL is not enabled in the "template1" database of your
PostgreSQL installation, you will have to enable it in "samizdat"
database manually:

   createlang plpgsql samizdat

It can be convinient to generate and subsequently manage Samizdat
database from ordinary account instead of "postgres" superuser. Replace
"angdraug" with your login name in the following command and later on:

   createuser angdraug

Allow yourself and "postgres" database superuser to connect using ident
authentication, and allow web server ("www-data") to connect as user
"samizdat". To achieve that, put following lines into pg_ident.conf (on
Debian, config files are located in /etc/postgresql and symlinked from
/var/lib/postgres/data):

   # MAP     IDENT    PGUSERNAME
   samizdat  postgres postgres
   samizdat  angdraug angdraug
   samizdat  www-data samizdat

Tell PostgreSQL to use the above mapping and to reject remote
connections. Make pg_hba.conf look like below (remove USER column for
PostgreSQL versions earlier than 7.3):

   # TYPE  DATABASE    USER     IP-ADDRESS     IP-MASK      METHOD
   local   samizdat    all                                  ident samizdat
   local   all         all                                  ident sameuser
   host    all         all      127.0.0.1      255.0.0.0    ident sameuser
   host    all         all      0.0.0.0        0.0.0.0      reject

Restart PostgreSQL.

Generate empty database with following lines:

   psql samizdat -f database/create.sql
   psql samizdat -f database/triggers.sql

If you use different PostgreSQL authentication method for Samizdat,
update Database#new method in samizdat/storage.rb accordingly.


Apache Setup
------------

Enable mod_ruby by putting the following line in Apache configuration
file (/etc/apache/httpd.conf on Debian) and restarting the Apache:

   LoadModule ruby_module /usr/lib/apache/1.3/mod_ruby.so

Depending on how your Apache is configured, path to mod_ruby.so can be
different, check where other LoadModule directives in your httpd.conf
point to.

If you fail to setup mod_ruby, Samizdat will fallback to running as a
set of plain CGI scripts, however, this mode of operation is not
recommended due to performance and compatibility considerations.

Unpack Samizdat into your document root (/var/www on Debian), or
anywhere else you want Samizdat to run from, and enable Ruby scripting
and URL rewriting by putting following lines into .htaccess file in that
directory (AllowOverrides options FileInfo, Indexes, and Options should
be enabled in Apache configuration for that directory):

   <IfModule mod_ruby.c>
      RubyRequire apache/ruby-run
      <Files *.rb>
         SetHandler ruby-object
         RubyHandler Apache::RubyRun.instance
      </Files>
   </IfModule>

   <IfModule !mod_ruby.c>
      <Files *.rb>
         SetHandler cgi-script
      </Files>
   </IfModule>

   Options +ExecCGI
   DirectoryIndex index.rb

   RewriteEngine on
   RewriteBase /samizdat
   RewriteRule ^([0-9]+)$ resource.rb?id=$1 [PT]

Change RewriteBase to point to the base location of your Samizdat site
(in the example above, "RewriteBase /samizdat" assumes that Samizdat was
unpacked as is into Apache document root). Update site:base option in
config.yaml to point to your base location, and replace "Localhost" with
the name of your site in site:name option.

To enable upload of multimedia messages, create a content directory
below web server document root and allow web server write access in this
directory. Update site:content option to point to the location of the
content directory relative to the document root (default "/content"
value assumes that you will create "content" directory right in the
document root). To disable multimedia upload, comment out site:content,
format:image, and format:other options in the config.yaml.


GetText Setup
-------------

List of available interface languages that is presented to the user is
defined via config.yaml. Make sure that the translations to the
languages you have listed there are available in the po/ directory in
Samizdat package (if you find that Samizdat is not yet translated to
your language of choice, please volunteer for this work and coordinate
with Samizdat developers).

For each of the selected languages (except English), generate MO-file
with msgfmt from GNU gettext or rmsgfmt from Ruby/GetText and place it
where GetText can find it:

   msgfmt po/$LANG.po -o /usr/local/share/locale/$LANG/LC_MESSAGES/samizdat.mo

If you are not able to place your MO-files in a standard location,
specify your own locale path in config.yaml, and make sure that files
under this path are readable by Samizdat scripts.


Pingback
--------

Pingback functionality relies on XML-RPC module for Ruby, which in turn
needs REXML or XML::Parser (see Required Software section).

To enable Pingback server in a Samizdat site, uncomment pingback options
in config.yaml and manually register special member with reserved login
name configured via pingback:login option:

   ruby -rsamizdat -e '
      db.do "INSERT INTO Member (login, full_name) VALUES (?, ?)",
      config["pingback"]["login"], config["pingback"]["full_name"]
      db.commit'

Creating pingback member this way instead of using Samizdat account
creation form leaves password field of the special member empty and
makes it impossible to log in as such member.

If pingback:login option is not defined, Pingback server will not be
advertised; if the option is defined, but no such member is registered,
Pingback server will fail with code 0x0031; when this option is defined
and such member exists, all Samizdat messages become pingback-enabled
resources.

When Pingback is properly enabled, all pings from other sites will be
published on behalf of the "pingback" member as text/uri-list replies to
the message identified by the target URI of the ping (ping target
resource). Each time when text/uri-list message is published by a real
member, Samizdat Pingback client will attempt Pingback server
autodiscovery on the first of the URIs included in the message.

Atomicity of Samizdat conceptual model requires that single message can
not include both a link to an external resource and a comment about it.
This requirement changes semantics of Samizdat Pingback client from what
is expected by the Pingback specification: it is not the ping source
resource itself that includes a comment about ping target resource, but
rather resources that are adjacent to the ping source in the Samizdat
knowledge base (in most common case, that is replies to the ping source;
in general, resources that are referred from the description of the ping
source resource).

If your Pingback server crashes, try to work around the incompatibility
between installed XML-RPC and mod_ruby versions by adding following
lines to your .htaccess:

   <Files pingback.rb>
      RemoveHandler .rb
      SetHandler cgi-script
   </Files>

This will force XML-RPC module to use ordinary CGI interface instead of
connecting to mod_ruby.


Samizdat on Windows
-------------------

Samizdat was successfully set up on Windows 98 with Cygwin (thanks to
Denis Valoha for details). In addition to default Cygwin components, you
will also need postgresql, gcc, make, perl, ruby, cygipc, and apache
packages. Ruby/Postgres and Ruby/DBI are not included in Cygwin, but can
be compiled from source according to installation instructions supplied
with these packages.

To initialize and start PostgreSQL under Cygwin, you will need to add
'ipc-daemon2.exe' invocation to your cygwin.bat, and then run from
Cygwin command line:

   initdb -D /var/postgres
   pg_ctl -D /var/postgres start


Running Tests
-------------

Samizdat test suite includes basic unit tests that check integrity of
the Samizdat code, and a more advanced robot that performs thorough
functional testing of a Samizdat installation.

To run basic unit test suite, you should have Test::Unit and REXML
modules for Ruby installed. Basic unit test suite is invoked by the
following command:

   ruby test/ts_samizdat.rb

Functional test also relies on Test::Unit and REXML, and uses Net::HTTP
module to interact with a working Samizdat installation, located from
the base URL of your config.yaml. This test is intended for a fresh
install of Samizdat engine; make ABSOLUTELY sure that you don't direct
this robot to a production site!

After you have made sure that you can connect directly to your web
server and double-checked your config.yaml, fire up the robot:

   ruby test/tc_robot.rb

If any of the tests report failure, please report output of the failed
test, accompanied by description of your system and versions of software
packages required by Samizdat (listed in Required Software section), to
Samizdat developers.

