Arbit - project tracking

Arbit installation guide

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

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 user-my validate-user

Where arbit is the prject you want to validate the user for and user-my is the database ID of the user.

The database ID is build from the string "user-" concatenated with the login name of the user. The login name here must be normalized, i.e. all special characters must be replaced by underscores ("_"). For example, if you chose "some!username" as your login, the database ID is "user-some-username".

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.

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 users database ID there, like:

administrator[]=user-my

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/*.