INSTALL

INSTALLATION (GNU/Linux)
========================

Follow these steps to install BW-Rox. Please note that there is a developer
Virtualbox image available at http://bewelcome.penpal4u.net/ which could save
you some work.

These steps have been tested on Debian/Ubuntu based systems. Commands,
usernames and locations might differ on your distribution.


Requirements
------------

  * Apache with mod_rewrite enabled
  * PHP version >= 5.1
  * PHP GD lib enabled
  * PHP short opening tags enabled
  * PHP magic quotes gpc disabled
  * MySQL server >= 5.1
  * SMTP server for email features


Download
--------

  1. Clone via Git:

      $ git clone git://gitorious.org/bewelcome/rox.git

  2. Done. For a fist look a simple read-only clone will do. See
     http://trac.bewelcome.org/wiki/Download for more details on branches and
     pushing code.


Create files and set permissions
--------------------------------

  1. Change to BW-Rox directory:

      $ cd /path/to/rox

  2. Create data directory for image uploads and working files:

      $ mkdir data

      $ touch \
          build/alias.cache.ini \
          build/autoload.cache.ini \
          modules/autoload.cache.ini \
          pthacks/autoload.cache.ini \
          tools/autoload.cache.ini \
          htdocs/exception.log

  4. Make things writable by webserver:

      $ sudo chgrp www-data \
          data \
          build/autoload.cache.ini \
          modules/autoload.cache.ini \
          tools/autoload.cache.ini \
          pthacks/autoload.cache.ini \
          build/alias.cache.ini \
          htdocs/exception.log

      $ sudo chmod g+rw \
          data \
          build/autoload.cache.ini \
          modules/autoload.cache.ini \
          tools/autoload.cache.ini \
          pthacks/autoload.cache.ini \
          build/alias.cache.ini \
          htdocs/exception.log


Database installation
---------------------

  1. Create database and set privileges:

      $ mysql -u root -p
      mysql> CREATE DATABASE bewelcome;
      mysql> GRANT ALL PRIVILEGES ON bewelcome.* TO 'bewelcome'@'localhost' IDENTIFIED BY 'bewelcome';
      mysql> FLUSH PRIVILEGES;
      mysql> exit

  2. Download development database dumps:

      $ wget http://downloads.bewelcome.org/for_developers/rox_test_db/bewelcome.sql.gz
      $ wget http://downloads.bewelcome.org/for_developers/rox_test_db/languages.sql.bz2
      $ wget http://downloads.bewelcome.org/for_developers/rox_test_db/words.sql.bz2

  3. Uncompress dumps:

      $ gunzip bewelcome.sql.gz
      $ bunzip2 languages.sql.bz2 words.sql.bz2

  4. Import dumps into database (first line needs root because of routines):

      $ mysql bewelcome -u root -p < bewelcome.sql
      $ mysql bewelcome -u bewelcome -pbewelcome < languages.sql
      $ mysql bewelcome -u bewelcome -pbewelcome < words.sql

  5. Remove dumps:

      $ rm bewelcome.sql languages.sql words.sql


Configure Apache
----------------

  1. Create a new virtual host file:

      $ sudo touch /etc/apache2/sites-available/bewelcome

  2. Edit virtual host file, add basic settings and rewrites:

      <VirtualHost *:80>
          ServerName bewelcome
          DocumentRoot /path/to/rox/htdocs
          ErrorLog /var/log/apache2/bewelcome-error.log
          CustomLog /var/log/apache2/bewelcome-access.log combined
          php_admin_value error_reporting "E_ALL"
          <Directory /path/to/rox/htdocs>
              RewriteEngine On
              RewriteBase /
              RewriteCond %{REQUEST_FILENAME} !-f
              RewriteCond %{REQUEST_FILENAME} !-d
              RewriteRule ^/*([^/]*)\.php /bw/$1.php [L,R,QSA]
              RewriteCond %{REQUEST_FILENAME} !-f
              RewriteCond %{REQUEST_FILENAME} !-d
              RewriteRule ^.* index.php [L,QSA,PT]
          </Directory>
      </VirtualHost>

     Note: Running BW-Rox in a sub directory (e.g. http:/localhost/bewelcome/)
     instead of the server root works, but is not recommended, because it
     complicates the setup and might cause unexpected behaviour.

  3. Add ServerName to your /etc/hosts file:

      127.0.0.1 bewelcome

  4. Enable virtual host:

      $ sudo a2ensite bewelcome
      $ sudo service apache2 reload


Configure BW-Rox
----------------

  1. Change to BW-Rox directory:

      $ cd /path/to/rox

  2. Create rox_local.ini based on rox_local.ini.example:

      $ cp rox_local.example.ini rox_local.ini

  3. Edit rox_local.ini and modify at least these sections to your needs:

       [db]
       [env]


Test and log in
---------------

  1. Point your browser to your BW-Rox installation (i.e. http://bewelcome/)

  2. Log in as user "henri" with no password. See "Useful hints" section below
     on password usage.

  3. Click around the site a bit and check if all CSS and images are loaded.
     Refer to /path/to/rox/htdocs/exception.log if errors appear or something
     looks broken.


Useful hints
------------

  * Geographical data:

    There are sample geographical data included in the developer database dump.
    If you need more geographical data, import the geonames dump:
    http://downloads.bewelcome.org/for_developers/rox_test_db/geonames.sql.bz2

  * Resetting all user passwords:

      $ mysql bewelcome -u bewelcome -pbewelcome
      mysql> UPDATE members SET password = PASSWORD("password");
      mysql> exit

    Note: Entering a password when logging in is only needed if
    "skip_password_check = false" in rox_local.ini.


Further help
------------

  Wiki: http://trac.bewelcome.org/wiki
  Mailing list: http://lists.bewelcome.org/mailman/listinfo/bw-dev-discussion
  Chat: #bewelcome on irc.freenode.net