Torii - portal application ~~~~~~~~~~~~~~~~~~~~~~~~~~ :Author: Arne Nordmann :Date: Thu, 20 Dec 2007 21:27:21 +0100 :Revision: 11 :Copyright: CC by-nc-sa :Description: Torii is a very simple portal application which easily allows writing and adding new modules. ======================== Torii installation guide ======================== .. contents:: Table of Contents :depth: 2 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. __ http://www.lighttpd.net/ __ http://httpd.apache.org/ 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_. __ http://httpd.apache.org/ __ http://www.lighttpd.net/ 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. .. include:: apache.htaccess :literal: 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. .. include:: lighttpd.conf :literal: 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. :: 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`__. __ /modules.html A similarized configuration could look like: :: torii
http://www.heise.de/newsticker/heise-atom.xml 40
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. __ /modules/feeds.html __ /modules.html 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 //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.