Installation & Configuration - Torii

Torii installation guide

Table of Contents

Prerequisite
Installation
- Installation from archive
- Checkout from SVN
Configuring the webserver
- Rewrite rules setup
- Modify directories
Configuration
Troubleshooting

The installation guide should help you with the initial setup and configuration of the Torii portal.

Prerequisite

There are some prerequisites your server should fulfill before Torii can be installed.

PHP 5.2

You should have at least PHP 5.2 installed. It may work with earlier versions of PHP, but we didn't test this.

PHP extensions

List of mandatory and useful PHP extensions.

SimpleXML, DOM, PCRE and SPL
These standard PHP extensions are mandatory for Torii and not only used by the modules, but also by the core.
JSON
The communication between the backend and the frontend is done using JSON encoding for the data. This PHP 5.2 extension is essential.
PDO & PDO/SQLite
Most of the modules, which need to store some data need the PDO/SQLite extensions to do so. You will find details on the test page mentioned later.
Curl
Most data from external site is fetched with curl, for example in the feed extensions. You may want to ensure, too, that this extension is installed.

Webserver

Some rewrite rules will be set up during the installation process, for Lighttpd and Apache rewrite rules are included in the distribution. If you are using another webserver you need to check its capabilities and probably adjust the rewrite rules.

Operating system

Some modules will not work on non POSIX compliant systems. Better directly use some more advanced operating system than Windows.

Installation

There are two possibilities to get the Torii files, either from SVN, or using a release archive.

Installation from archive

Download and extract an archive listed on the download page. The archive contains a folder which name matches the version you downloaded. You may just upload its contents to your webhost. The following folder structure is given:

classes/: Contains internally used PHP classes, should not matter for you.
conf/: Contains the user configuration. We will come back to this later in the configuration section.
data/: All data will be stored here. Should be writeable for the webserver user.
doc/: Contains documentation on Torii. You may find other helpful documentation here.
htdocs/: This folder is assumed to be accessed by the webserver. It only contains the index.php, some images and style files.
module/: The modules are stored here. If you write a new one, or download one, just copy it to this folder.
templates/: The styles are stored in this folder. We will come back to this later in the configuration section.

Checkout from SVN

You may also do a direct checkout from SVN if you want to use the most recent development results from trunk. We try to keep even the trunk stable and most of the developers are using the trunk version in their day-to-day usage. You may get unstable or non-working versions in rare cases.

The trunk checkout will contain the same folder structure as described for the archive above. You may check it out using the following command on the shell or your favourite SVN client.

svn checkout svn://torii-portal.org/torii/trunk torii

After this you find a directory torii/ at the location you checked it out to. You may update in future by using 'svn update', which contains the same folders described above and is usable in exactly the same way.

Configuring the webserver

As mentioned above the webserver should point to the htdocs/ subfolder of the distributed files. Beside this you just need to set up correct rewrite rules.

Rewrite rules setup

There are rewrite rules included in the doc/ directory for Apache and Lighttpd.

Apache

Just copy the file 'doc/apache.htaccess' to 'htdocs/.htaccess'. If mod_rewrite is enabled in your apache installation everything should work just fine then.

# Apache rewrite rules by Andreas Schamberger

RewriteEngine on
RewriteBase /

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
# handle feed redirect calls extra, because one slash of http:// gets lost in the call
RewriteRule ^([a-zA-Z0-9_]+)/([a-zA-Z0-9_]+)(?:/http:/(.*))?$ /index.php?module=$1&action=$2&parameter=http://$3 [L]

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^([a-zA-Z0-9_]+)/([a-zA-Z0-9_]+)(?:/(.*))?$ /index.php?module=$1&action=$2&parameter=$3 [L]

# If you use apache with fcgi the $_SERVER variables PHP_AUTH_USER and 
# PHP_AUTH_PW aren't set, so you cannot login. It seems to be an old 
# problem. 
#
# http://bugs.php.net/bug.php?id=35752
#
# Here is a workaround, just comment out the following rule, it passes
# the base64 encoded authorization data to the php environment.
#
#RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

Lighttpd

As you know when using lighttpd you need to add the rewrite rules to the server configuration and restart lighttpd after that. The rewrite rules you need can be found in the file 'doc/lighttpd.conf', which will only work with my vhost setup, but you should get the point.

$HTTP["host"] =~ "(^|\.)portal$" {
    var.localroot = vhostbase + "/portal"

    server.document-root = localroot + "/htdocs/"
    
    include "vhost/includes/fastcgi.conf"
    include "vhost/includes/locallog.conf"

    url.rewrite-once = (
        "^/favicon.png$" => "$0",
        "^/robots.txt$" => "$0",
        "^/check.php$" => "$0",
        "^/style/.*" => "$0",
        "^/images/.*" => "$0",
        "^/script/.*" => "$0",
        "^/([a-zA-Z0-9_]+)/([a-zA-Z0-9_]+)(?:/([^?]*))?(?:\?(.*))?$" 
            => "/index.php?module=$1&action=$2&parameter=$3&$4",
        "^/?$" => "index.php",
        ".*" => "error.php"
    )
}

Modify directories

If you want to choose another directory setup you can do so, because all locations are configured in the config.php in the webroot. For example you may move all content in the htdocs/ folder to the root folder of your Torii installation and change the first lines in the config.php like:

define( 'TORII_CONF_PATH',
    realpath( dirname( __FILE__ ) . '/conf/' ) );
define( 'TORII_DATA_PATH',
    realpath( dirname( __FILE__ ) . '/data/' ) );
define( 'TORII_CLASS_PATH',
    realpath( dirname( __FILE__ ) . '/classes/' ) );
define( 'TORII_TEMPLATE_PATH',
    realpath( dirname( __FILE__ ) . '/templates/' ) );
define( 'TORII_MODULE_PATH',
    realpath( dirname( __FILE__ ) . '/module/' ) );
define( 'TORII_HTDOCS_PATH',
    realpath( dirname( __FILE__ ) . '/htdocs/' ) );

You may of course also do something completely different.

Configuration

The configuration process consists of two steps. First you need to define the portal configuration with its sections and the modules you may want to install. Then you may select another template beside the default template.

Configuring your modules

Beside the general configuration each module may have its own configuration, which is described on the module pages or may be found in the example configuration.

First copy the example.xml in the config/ folder to a file matching your desired username, like kore.xml for the user name 'kore'. This will be the user you need to authorize against when accessing the portal. After this edit the configuration file with your favourite text or XML editor.

General configuration

For now there is only one setting in the general section, the password required for authorization. This password will be used together with the above defined username for HTTP-Authorization when you access the portal.

<?xml version="1.0" encoding="UTF-8"?>
<torii>
    <general>
        <password>torii</password>
    </general>
    <!-- ... -->
</torii>

Changing the password should be obvious enough to not need any further explanations.

Sections & Modules

Let's start with a short definition:

Section: Sections are the structure, modules are put in. Most layouts will use the sections as the columns the modules will be displayed in. You may define any number of sections, but keep in mind, that too few or too less sections may cause weired layouts. Usually three sections are a good choice.
Modules: The central element of Torii. Modules implement custom functionalities, like a feed aggregator or similar. You can find a list of modules on the website.

A similarized configuration could look like:

<?xml version="1.0" encoding="UTF-8"?>
<torii>
    <general>
        <password>torii</password>
    </general>
    <section>
        <module type="feed" id="it_news" name="IT News">
            <feeds>
                <feed id="Heise">http://www.heise.de/newsticker/heise-atom.xml</feed>
                <!-- ... -->
            </feeds>
            <count>40</count>
        </module>
    </section>
    <section>
        <module type="weather" id="weather" name="Wetter">
            <!-- ... -->
        </module>
        <module type="feed" id="news" name="Nachrichten">
            <!-- ... -->
        </module>
        <module type="anysms" id="anysms" name="Send SMS">
            <!-- ... -->
        </module>
    </section>
    <section>
        <!-- ... -->
    </section>
</torii>

Below the earlier described general configuration section you can see three sections, each containing some modules. The number of modules in a section has no hard limit. You can see that each module has some attributes in common.

type
The type of the module matches the name of the directory in modules/ directory. It defines the type of the module which should be instantiated at this position of the portal.
id
The ID should be unique for your configuration and will be used by the frontend and backend scripts to identify and reference the module.
name
The name will be displayed as a title for the module. Use whatever you want here.

The module configuration itself, as you can see for the feed module in the above example is described per module in the module section on the website.

Testing your setup

Torii offers a test script which checks for common errors and the availability of all required PHP extensions for each module. Some modules may also implement some content and configuration checks. You can test the configuration by calling the URL http://torii/check.php in your browser, where 'torii' is the configured host, and optionally a configured path before '/test.php'. The script may take some time to load but offers you enough information to locate possible problems.

Using the portal

You may finally use the portal by calling the URL to your portal in your browser and just start using it.

Troubleshooting

Common problems and ways to diagnose the problem.

Module does not show data
If one module does not load or show data use a JavaScript debugger for your browser and take a look at the messages. In most cases Torii will throw an Exception with a readable message, which describes the problem and offers you some way to solve the problem.
How to debug an erroneous module?
You can check the modules response directly in your browser. Just call the URL /<moduleID>/renderData/ and inspect the result. It should be a JSON response without any other output. If there are any PHP notices, errors or other output, fix it. :)
Will Torii ever work with MS Internet Explorer?
No. Never. It was tested with Firefox, Opera and Konqueror and runs fine with these free browsers.
Will Torii run on Microsoft Windows?
I don't know and I don't care.
Will you accept patches, so that this propretary MS crap will be supported?
No. There is no way for me to test MS setups. And you will agree with me that I should not distribute untested software or setups.

Installation & Configuration Torii - portal application

Search

Contents