root/trunk/INSTALL

= Installing Motilee =

Motilee is a regular symfony application. It requires only the files located under its own folder. Installing Motilee is quite straightforward if you already configured a symfony application before. If you don't know symfony, just follow this step-by-step tutorial and you should be done in a matter of minutes.

== Fast installation ==

Download the motilee tarball from [http://www.motilee.com/motilee.tgz]. Unpack it under your web root. Then browse to:

{{{
http://localhost/motilee/frontend_dev.php
}}}
    
You can test the application by browsing and searching the forums (populated with test data), creating a new user, adding a new message in a topic or creating a new topic in a forum. Eventually, don't forget to take a look at the administration interface by logging in as admin/admin.

== Installation requirements ==

Motilee is a PHP5 forum relying on the symfony framework. The framework files are bundled with the application, so you don't need to install symfony before installing Motilee. However, you will definitely need a server capable of running PHP5 scripts, preferably Apache with `mod_php`. Recommended PHP version is 5.2.3.

As for the database, Motilee comes with a bundled SQLite databae, but can run on MySQL, SQLServer, PostgreSQL, and Oracle.

Eventually, Motilee is system agnostic, so it will run on *nix systems a well as on Windows systems.

== Reminder on symfony deployment ==

Motilee doesn't come with a graphical user interface for installation, because you should not let your server change files that are not under the public web root. Only the files located under the `motilee/web/` directory should be directly accessible from the web.

This means that an installation of Motilee requires in two steps:

 - Unpack, configure and test Motilee on a local server, for instance on your very desktop computer. You should have access to a command line on this server, especially if you want to run the application on MySQL. The server configuration should be as similar as possible to the production one.

 - When the application runs locally, transfer the files to production, either via (S)FTP, or via the preferred rsync-over-ftp method recommended by symfony.

This is the same as for all symfony applications. If you want to learn more about symfony, and good practices of web applications deployment, refer to the [http://www.symfony-project.org/book/1_0/03-Running-Symfony symfony book].

== Downloading the application ==

Motilee comes in two flavors:

 - A preconfigured tarball, bundled with a SQLite database populated with test data. Download it at [http://www.motilee.com/motilee.tgz]. This version is completely customizable, ready to run out of the bix, but you may find it difficult to update it.
 
 - A checkout from the motilee SVN repository, located at [http://svn.motilee.com/trunk]. This version is easier to upgrade, but requires an extra installation step. Once you have all the files downloaded to a directory, open a terminal, browse to the motilee directory, then build the object model with the symfony command line, and load the test data. If you are not familiar with the symfony commands, you just need to copy the following commands:

{{{
$ cd /path/to/motilee
$ php symfony propel-build-all
$ php symfony clear-cache
$ php symfony propel-load-data frontend
}}}

== Web server configuration ==

The configuration of the web server may differ between the local server and the production server. Three methods are proposed here, choose the one that best fits your needs and constraints.

=== Zero configuration ===

This method requires no change in web server or database configuration. It should work out of the box on all systems and is a good way to test the application and see if it fits your needs. However, you should not use this method in production, as it gives access to scripts and data files that should remain hidden to the end user.

The installation is really straightforward: Move the motilee files under the web root folder of your web server. Of course, you can directly unpack the tarball or do the repository checkout there.

You should end up with a file structure similar to:

{{{
Apache/
  www/
    motilee/
      apps/
      batch/
      cache/
      config/
      data/
      doc/
      lib/
      log/
      plugins/
      test/
      web/
        sf/
        index.php
        frontend_dev.php
        ...
}}}

That's all. Now test motilee by browsing to:

{{{
http://localhost/motilee/web/frontend_dev.php
}}}

=== Custom web root ===

A better way to install motilee is to put the content of the motilee/web/ folder under your web root, and the rest under another directory outside of the web root. Let's assume that your host offers you two directories for your applications:

{{{
my_site/
  cgi-bin/
  www/
}}}

Unpack (or transfer by ftp) all directories but the `web/` one under `cgi-bin`, and unpack (or transfer) the files of the `web/` directory under `www/`. You should end up with a file structure similar to:

{{{
my_site/
  cgi-bin/
    apps/
    batch/
    cache/
    config/
    data/
    doc/
    lib/
    log/
    plugins/
    test/
  www/
    sf/
    index.php
    frontend_dev.php
    ...
}}}

Edit both the `index.php` and the `frontend_dev.php` files and change the third line to:

{{{
define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/../cgi-bin'));
}}}

Then, you need to change the motilee web root configuration by editing the file called `cgi-bin/apps/frontend/config/config.php`. You should ad the following lines at the end of the file:

{{{
$sf_root_dir = sfConfig::get('sf_root_dir');
sfConfig::add(array(
  'sf_web_dir_name' => $sf_web_dir_name = 'www',
  'sf_web_dir'      => $sf_root_dir.DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.$sf_web_dir_name,
  'sf_upload_dir'   => $sf_root_dir.DIRECTORY_SEPARATOR.'..'.DIRECTORY_SEPARATOR.$sf_web_dir_name.DIRECTORY_SEPARATOR.sfConfig::get('sf_upload_dir_name'),
));
}}}

Check that the installation went fine by browsing to:

{{{
http://www.mysite.com/frontend_dev.php
}}}

=== Virtual Host ===

Create a new virtual host to be able to access the forum application. To do so, open your Apache configuration's `httpd.conf` and add the following lines at the end:

{{{
<VirtualHost *:80>
  ServerName motilee.mysite.com
  DocumentRoot "/path/to/motilee/web"
  DirectoryIndex index.php
  <Directory "/path/to/motilee/web" >
    AllowOverride All
    Allow from All
  </Directory>
</VirtualHost>
}}}

Replace `motilee.mysite.com` by the URL you want to give to the forum application, and `/path/to/motilee/` by the absolute path to the `motilee` directory in your system. After saving the file, you should restard Apache and check that the installation went fine by browsing to:

{{{
http://motilee.mysite.com/frontend_dev.php
}}}

=== Troubleshooting ===

If you can't see the welcome screen, start by clearing the cache. To do so, type the following command from the root of the motilee directory:

{{{
$ php symfony clear-cache
}}}

Try to reach the test page at `http://motilee.mysite.com/default/index`. If the problem persists, switch to the development environment to see explicit error messages by browsing to:

{{{
http://motilee.mysite.com/frontend_dev.php
}}}

Depending on your host, you may also have to edit the rewriting rules located in `web/.htaccess`. Here is the default file:

{{{
Options +FollowSymLinks +ExecCGI

<IfModule mod_rewrite.c>
  RewriteEngine On

  # uncomment the following line, if you are having trouble
  # getting no_script_name to work
  #RewriteBase /

  # we skip all files with .something
  RewriteCond %{REQUEST_URI} \..+$
  RewriteCond %{REQUEST_URI} !\.html$
  RewriteRule .* - [L]

  # we check if the .html version is here (caching)
  RewriteRule ^$ index.html [QSA]
  RewriteRule ^([^.]+)$ $1.html [QSA]
  RewriteCond %{REQUEST_FILENAME} !-f

  # no, so we redirect to our front web controller
  RewriteRule ^(.*)$ index.php [QSA,L]
</IfModule>

# big crash from our front web controller
ErrorDocument 500 "<h2>Application error</h2>symfony application failed to start properly"
}}}
        
If you still can't manage to setup the application correctly, refer to the [http://www.symfony-project.org/book/1_0/03-Running-Symfony#Troubleshooting symfony documentation] or find help in the [http://www.symfony-project.org/forum/index.php/f/6/ symfony forum].

== Database configuration ==

By default, Motilee runs a SQLite database located under `motilee/data/sandbox.db`. If your forum has a relatively low activity or if you don't want to setup a database, you can just keep the configuration as it is and upload the `sandbox.db` with the rest of the files. The application will run smoothly without further configuration.

If you want tu use another database vendor, you will need to create the database first, then edit two files located in `motilee/config/`.

To create your database, use either your database command line or any client interface it comes with. For instance, if you want to use MySQL, you can type:

{{{
$ mysqladmin -uroot -p create motilee
}}}

Change `motilee` to whatever name you want to give to your database.

The first configuration file to change is `propel.ini`. Symfony uses this file to determine the database connection when called via the Command Lne Interface (CLI). It will help you define a database structure in a list of SQL statements adapted to your database vendor. For instance, if you want to use the MySQL database just created:

{{{
// In motilee/config/propel.ini
// Modify lines 5 to 7 as follows
propel.database            = mysql
propel.database.createUrl  = mysql://login:passwd@localhost/
propel.database.url        = mysql://login:passwd@localhost/motilee
}}}

The Database Source Name (DSN) shown here follows PEAR-style DSN string conventions, as explained in the [http://creole.phpdb.org/trac/wiki/Documentation/CreoleGuide Creole guide]. The database vendor can be any of `mysql`, `sqlserver`, `pgsql`, `sqlite` and `oracle`.

Use the symfony command line to generate the SQL code necessary to create the tables.

{{{
$ php symfony propel-build-sql
}}}

The generated SQL code lies under `motilee/data/sql/`. It consists of several `.sql` files that you can either open and execute one by one (through the database command line or via a PHPMyAdmin interface), or inject all at once to your database by using the symfony command line:

{{{
$ php symfony propel-insert-sql
}}}

This will create all the tables necessary to handle the forum topics, posts, views, etc.

The second file that must be edited if you don't use SQLite is the `databases.yml`. Symfony uses this file to determine the database connection at runtime. It must point to the same database DSN as the one defined in the `propel.ini`.

{{{
// In motilee/config/databases.yml
// Modify lines 11 and 12 as follows
all:
  propel:
    class:      sfPropelDatabase
    param:
      phptype:  mysql
      database: mysql://login:passwd@localhost/motilee
}}}

To test this setting, you can load the test data into the database by calling the symfony command line:

{{{
$ php symfony propel-load-data frontend
}}}

For more information on database connection settings, you can refer to the [http://www.symfony-project.org/book/1_0/08-Inside-the-Model-Layer#Database%20Connections symfony model documentation].

== Managing users, forums and categories ==

To define categories and settings, go to the administration interface at the URL:

{{{
http://motilee.mysite.com/forumAdmin
}}}

You will be requested to log in. The default administrator login and password are admin/admin. You can use the administration interface to change the default administrator login (and you should).

== Forum configuration ==

To start configuring the forum, copy the sample application configuration file `motilee/apps/frontend/config/app.yml.sample` to `motilee/apps/frontend/config/app.yml`. You can then modify this new file at will. The default configuration is reproduced below:

{{{
  all:
    sfSimpleForumPlugin:
      forum_name:             Motilee forums
      display_categories:     true
      use_feeds:              true  # requires sfFeed2Plugin
      count_views:            true  # count each time a topic is viewed. Turn off to increase performance
      max_per_block:          10    # maximum number of links displayed in a block
      include_breadcrumb:     true  # include breadcrumb slot content. Turn off if you don't use the breadcrumb.
      breadcrumb_separator:   ' » ' # separator for breadcrumb trail
      max_per_page:           10    # maximum threads or messages per page
      pages_displayed:        5     # maximum pages displayed by the pager navigation
      feed_max:               10    # maximum messages served by feed
      show_author_details:    false # display number of messages of post authors
      allow_new_topic_outside_forum: true

    sfModerationPlugin:
      auto_register_behavior: false
}}}