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

- Get the Required Software
- Install Samizdat Engine
- One Code To Run Them All
- Uploads and Other Site-specific Content
- Object Cache
- Create Database
- Connect to the Database
- Web Server Configuration
- Email Interface
- Syndication
- Running Tests


Get the Required Software
-------------------------

You need the following software to run Samizdat: Ruby programming
language environment, Rack web server interface with a compatible web
server, PostgreSQL database with enabled PL/pgSQL procedural language
(MySQL and SQLite3 support is currently outdated), and the following
Ruby libraries: Graffiti, Sequel, and Pg for database access; SynCache
object cache; Whitewash and Nokogiri to sanitize user-submitted HTML;
Magic to detect format of uploaded files; RMagick for image
manipulation.

Additional recommended libraries are: FastGettext or Ruby-GetText for
translation of user interface to different languages, algorithm/diff for
version comparison, RedCloth for Textile hypertext markup, TZInfo for
timezone conversions. Samizdat will still work if the recommended
libraries are not present, but the corresponding parts of functionality
will not be there.

   http://samizdat.nongnu.org/
   http://ruby-lang.org/
   http://rack.rubyforge.org/
   http://www.postgresql.org/
   http://sequel.rubyforge.org/
   http://bitbucket.org/ged/ruby-pg
   http://nokogiri.org/
   https://github.com/qoobaa/magic
   http://rubyforge.org/projects/rmagick/
   https://github.com/grosser/fast_gettext
   https://github.com/mutoh/gettext
   http://packages.qa.debian.org/r/ruby-algorithm-diff.html
   http://rubyforge.org/projects/redcloth/
   http://rubyforge.org/projects/tzinfo/

On Debian or Ubuntu, just install samizdat package (you may also want to
check for a newest version in the experimental archive), and follow the
instructions there.


Install Samizdat Engine
-----------------------

If you can't use the Debian package of Samizdat, use Minero Aoki's
setup.rb script supplied with Samizdat source:

   ruby setup.rb all

Check --help if you want to change default paths, use --no-harm option
to check where the files will go. Make sure that *.yaml files go to
/usr/local/share/samizdat, or put it in a place where Samizdat can find
it (see SiteConfig::CONFIG_DIRS in engine/deployment.rb).

Unfortunately, setup.rb doesn't do all the job: it doesn't know anything
about CGI scripts and PO localization files, so these have to be
installed manually. Copy cgi-bin directory to /usr/local/share/samizdat,
generate .mo files from po/*.po (using msgfmt from GNU gettext or
rmsgfmt from Ruby/GetText) and place them where gettext can find them:

   cp -R cgi-bin /usr/local/share/samizdat/
   mkdir -p /usr/local/share/locale/$LANG/LC_MESSAGES
   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, you
will have to specify your own locale path in /etc/samizdat/defaults.yaml
or in your site-specific config file.


One Code To Run Them All
------------------------

The preferred way to run Samizdat is to have all sites share the same
code installed under /usr, and have site configurations under
/etc/samizdat. To achieve that, copy sites.yaml and defaults.yaml to
/etc/samizdat and create the /etc/samizdat/sites directory. For each
of your sites, create <site-name>.yaml in /etc/samizdat/sites/, using
config.yaml as a template:

   mkdir -p /etc/samizdat/sites
   cp data/samizdat/{sites,defaults}.yaml /etc/samizdat
   cp data/samizdat/config.yaml /etc/samizdat/sites/samizdat.yaml

This is the way the Debian package of Samizdat sets things up.

Later on you should customise <site-name>.yaml as the main
configuration file for your Samizdat site. You may transfer parts of
defaults.yaml to each <site-name>.yaml if your separate sites require
more specialisation of configuration parameters.


Uploads and Other Site-specific Content
---------------------------------------

Wherever you put standard Samizdat files and configs, every site needs a
bit of its own room, some place that will be served directly by your web
server, without involvement of Samizdat application.

At the very least, you need some directory to store the files uploaded
by your users. By default, these files go to "content" subdirectory of
your site base directory, this location is specified in site:content_dir
option in your site-specific config file, you can also comment this
option out to disable file upload on your site. Wherever you place this
directory, make sure it is writeable by the web application ("www-data"
user if you use Apache + Passenger, or "samizdat" user if you use the
supplied Thin and Nginx config examples) and served by your Web server
from the location you specify in site config.

Other things that are served from site base directory may include site
logo, favicon, and static fragments included from the front page. There
are no restrictions on how you set these up, just don't put them inside
the writable content directory.


Object Cache
------------

If at all possible, configure your site to use the SynCache dRuby object
cache server. It provides syncronized object cache for multiple web
server processes, improving cache consistency and overall performance.
In addition to caching, SynCache syncronizes the database access, so
that identical queries only hit the database server once, and the result
is then propagated to all processes that requested this data.


Create Database
---------------

If you're in a hurry, just run as root (replace "samizdat" with the name
of your site):

   samizdat-create-database samizdat pgsql

This script will generate a database with empty tables and triggers,
create a PostgreSQL user with the same name, and grant that user all
necessary access rights.

You can do the same things manually, this will give you a better idea of
how things are organized and how to fix when they break. Run the
following as postgres superuser:

   createdb --encoding UNICODE samizdat
   createuser -SDR samizdat
   createlang plpgsql samizdat

   cd /usr/local/share/samizdat/database
   psql samizdat -f create-pgsql.sql
   psql samizdat -f triggers-pgsql.sql
   psql samizdat -f grant-pgsql.sql

If you use non-default database and user name (for example, if you have
more than one site on the same machine), replace "samizdat" with your
database and user name in the above examples, and run grant-pgsql.sql
through sed before feeding it to psql:

   sed -e 's/samizdat/username/g' grant-pgsql.sql | psql dbname


Connect to the Database
-----------------------

To let Samizdat know how to connect to the database you've just created,
you should specify database access details in the "db" section of your
site-specific config file. Make sure this file cannot be retrieved by
your users: if someone gains direct access to your database, they can do
whatever they want to your site without you ever knowing it.

Luckily, PostgreSQL's IDENT authentication mechanism allows you to avoid
storing database passwords anywhere: if you have full control over
PostgreSQL configuration and run it on the same host as your web server,
you can allow your web server connect to your database without password,
using underlying Unix system's authentication instead.

Read below on how to configure PostgreSQL for IDENT. If you can't have
this luxury, use pwgen to generate a secure password and move on to the
next session.

First, create a separate database user for yourself, so that you don't
have to switch to postgres superuser to do maintainance of your
database. Replace "angdraug" with your login name in the following
command and later on:

   createuser angdraug

Allow yourself and "postgres" database superuser to connect under the
same name 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 under
/etc/postgresql, on some systems they are located in PostgreSQL data
directory instead):

   # MAP     IDENT    PGUSERNAME
   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 (if you're running
PostgreSQL version older than 8.4, format of this file will be slightly
different, check your PostgreSQL documentation):

   # TYPE  DATABASE  USER     CIDR-ADDRESS  METHOD
   local   all       postgres               ident

   local   samizdat  all                    ident map=samizdat

   local   all       all                    ident
   host    all       all      127.0.0.1/32  md5
   host    all       all      ::1/128       md5

Since order of the lines in pg_hba.conf is important, make sure that
Samizdat line appears before any other lines that might match, but not
above the line that ensures that postgres superuser can always login.

Restart PostgreSQL, try to connect:

   psql samizdat

Now comment out the "password" option in the "db" section of the site
configuration file to let PostgreSQL know that you want to use IDENT
authentication.

If you want a more complicated database connection scheme, replace the
Site#db() method in lib/samizdat/engine/site.rb to connect to any
databases in whichever way you like.


Web Server Configuration
------------------------

You can run Samizdat with any Rack-compatible application server. See
doc/examples/samizdat-thin.yaml for an example of Thin configuration.
Alternatively, you can quickly start Samizdat in development mode (using
either Mongrel or Webrick) with the following command:

   rackup /usr/local/share/samizdat/cgi-bin/samizdat.ru

Generally, it's not a good idea to let the application server face the
world directly and serve static content, you should put it behind a
light-weight web server such as Nginx. Under doc/examples/nginx/ you
will find a modular set of configuration files for Nginx that makes it
easy to run multiple Samizdat sites on a single server. All you have to
do to add another site is create a copy of sites-available/samizdat and
update server_name, root, and access_log parameters. If you want to use
another backend server instead of Thin, update server parameter in
conf.d/samizdat.conf.


Email Interface
---------------

Samizdat can verify users' emails (this gives some protection from
automated mass-registration of fake identities) and recover accounts
with lost passwords. To enable these features, uncomment the email
section of defaults.yaml, or configure it differently for each of your
sites. Make sure that the sendmail program you specify is able to send
emails to the outside world, and provide a valid email address on the
same domain as the webserver, so that Samizdat's emails are not blocked
by spam filters.


Syndication
-----------

Samizdat supports both export and import of RSS feeds. You can subscribe
to a feed of featured articles, recent updates, updates in a particular
tag, or even a feed composed by results of an arbitrary RDF query. Pages
that have RSS versions will have "rss 1.0" link at the bottom and may
also be highlighted in your browser.

To have several RSS feeds imported by Samizdat, uncomment and edit
"import_feeds" section of your site's config file, and schedule
samizdat-import-feeds script run at regular intervals on same server
that runs your site. Do not make it run more often than absolutely
necessary, to avoid overloading the servers where you will be importing
feeds from.

The imported feeds will be sorted alphabetically by name and displayed
on the front page in the "Links" section.


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 and integration testing of a Samizdat installation.

Basic unit test suite is invoked by the following command:

   ruby -I. test/ts_samizdat.rb

Functional test uses Net::HTTP module to interact with a working
Samizdat installation. This test is intended for a fresh install; make
ABSOLUTELY sure that you don't direct this robot to a production site!

By default, functional test runs against a 'samizdat' site defined in
the configuration examples. If you don't have such site configured or
want to run the tests for a different site specified in your sites.yaml,
you will need to set environment variables SAMIZDAT_SITE, SAMIZDAT_URI,
and SAMIZDAT_HOST (see defaults as set in test/tc_robot.rb).

The test makes several assumptions about the configuration of the site.
Email interface should be disabled (this is necessary because the test
uses fake email addresses for account creation and can't respond to
confirmation requests), post access for guests should be denied (this is
used to test access controls), and vote access for members should be
allowed. Your SynCache server should run without rate limit (no
--flush-delay, comment out FLUSHDELAY line in /etc/default/syncache).

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

   ruby -I. test/tc_robot.rb

If any of the tests report failure, please send us output of the failed
test (including errors reported in web server error log in the case of
functional test), accompanied by description of your system and versions
of software packages required by Samizdat (listed in the Required
Software section).

