Arbit - project tracking

INSTALL

========================
Arbit installation guide
========================

.. warning:: This article is a stub, please help us extending it with more
    detailed information.

This document will help you to set up an arbit instance.

Prerequisite
============

The minimum prerequisite for installing arbit currently are:

- A webserver with PHP 5.3

  We are not aware of any non default PHP extensions required for arbit.
  OpenSSL support is required for optional OpenID authentification.

- A running CouchDB__ instance, with the minimum version 0.9.0

__ http://incubator.apache.org/couchdb/downloads.html

Installation
============

There are two variants of installation. You only need to perform one of the
following actions, `Linking`_ or `Copying`_. On a system supporting links, you
should probably chose the first one.

Linking
-------

Link the htdocs/ folder from arbit to your webroot itself or a subdirectory in
your webroot.

Copying
-------

Copy the complete arbit instance ton one directory above your webroot and
configure your webserver to serve the htdocs/ folder from arbit as you webroot.

Some files from the folders above the actual htdocs/ directory, like the cache,
config and log files, should not be accessible from the web.

Webserver configuration
=======================

There are two ways to configure your webserver to get arbit working. Either
configure the index.php as your 404-error-handler, or rewrite all requests,
except for the images/, styles/ and scripts/ directories to the index.php.

Arbit may reside inside some subdirectory like http://example.org/arbit/ or
directly in the vhost root, like http://example.org. Both should be handled
properly by arbit itself.

Apache example configuration
----------------------------

You can configure arbit to either reside in the vhost root, or in some
subdirectory. A .htaccess files with the required rewrite rules is provided in
the htdocs/ directory. The rewrite rules should look like::

    RewriteEngine On
    
    RewriteRule images/.* $0 [L]
    RewriteRule styles/.* $0 [L]
    RewriteRule scripts/.* $0 [L]
    RewriteRule .* index.php [L,QSA]

Everything else should just work like known from apache.

Lighttpd example configuration
------------------------------

A lighttpd example configuration using a 404-error-handler could for example
look like::

    $HTTP["host"] =~ "^arbit$" {
        var.localroot = vhostbase + "/arbit"
        server.document-root = localroot + "/htdocs/"

        server.error-handler-404 = "/index.php"
    }

You may also use rewrite rules with lighttpd, like with apache. The
configuration then would look like::

    $HTTP["host"] =~ "^arbit$" {
        var.localroot        = vhostbase + "/arbit"
        server.document-root = localroot + "/htdocs/"

        url.rewrite-once = (
            "^/(?:images|styles|scripts)/.*" => "$0",
            "^/.*" => "index.php",
        )
    }

Yaws example configuration
--------------------------

A Step by Step Guide to configure Yaws for arbit. (If you use fcgi, there is an
modification needed) First you need to write and compile an 404-error-handler.
Write the following code in arbit_404_handler.erl::

    -module(arbit_404_handler).

    -include("yaws/include/yaws.hrl").
    -include("yaws/include/yaws_api.hrl").

    -export([out404/1,
         out404/3,
              crashmsg/3]).

    out404(Arg) ->
         out404(Arg, get(gc), get(sc)).
    out404(Arg, GC, SC) ->
         yaws_cgi:call_cgi(Arg, GC#gconf.phpexe,  lists:flatten(Arg#arg.docroot) ++ "/index.php").

    crashmsg(_Arg, _SC, L) ->
         {ehtml,
          [{h2, [], "Internal error, yaws code crashed"},
           {br},
           {hr},
           {pre, [], L},
           {hr}]}.

compile it direct to the right dir for Yaws::

    erlc -o /var/yaws/ebin -I /usr/locale/lib arbit_404_handler.erl

Set the php_exe_path in the yaws.conf and add the 404-error-handler for the
virtual host::

    <server arbit.example.com>
        port = 80
        listen = 127.0.0.1
        allowed_scripts = php cgi yaws
        docroot = /path/to/arbit/htdocs
        errormod_404 = arbit_404_handler
    </server>

If your arbit installation resides in some subdirectory you should modify the
rewrite rules accordingly.

Arbit configuration
===================

Arbit configuration is completely done in config/ directory of you checkout.
There are two configuration files you are required to edit. The first is the
config/main.ini. There you configure the overall used projects and modules.
Most of the configuration items should be self descriptive, and all are
documented.

For the project you need to create a folder with the identifier of your
project, which contains a project.ini with your project configuration. As a
template for this configuration file you may copy the project.ini from the
example project.

.. note:: Core is the "project" which contains the overall administrative
    features and dashboard, therefore you cannot use "core" as your project
    name.

Register first user
===================

To register a user, simply open the URL of your Arbit installation and register
a user.

All user registrations currently need to be confirmed by clicking on the
confirmation link in the registration email. Those are often not sent out on
development hosts. In this case you can activate accounts manually using the
manage command on the command line interface::

    ./scripts/usr/manage -p arbit -u username validate-user

Where ``arbit`` is the project you want to validate the user for and
``username`` is your login name or the OpenID URL you used to register.

Administrators can use the arbit interface to confirm user accounts, which can
be found at "The project" -> "Users". You will see how to become an admin in
the next section.

__ http://localhost:5984/_utils/

Get administrator access
------------------------

To get administrator access with you user, you should edit the configuration
file ``config/$project/project.ini``. In the ``[user]`` section you can add any
number of administrators. Add your login or OpenID URL, like::

    administrator[]=username

Where ``username`` is either your login name or the OpenID URL you used to
register. Re-login into your Arbit instance afterwards and you should have the
permission to do anything.

Manage your instance
====================

For administrative tasks like cache clearing and similar there is a command
line tool, which can help you with this. For more information on the available
commands just run::

    ./scripts/usr/manage -h

For backups and imports there is another backend specific tool. It can be used
to im- and export back end data of your projects. For more details just call::

    ./scripts/usr/couchdb -h

Some modules also may have scripts for administrative tasks, like the source
module has. They are normally located somewhere like ``./modules/*/scripts/*``.