**********************************************************
    
    install.txt
    
    @author gERD Schaufelberger <gerd@exit0.net>
    @copyright 2004/2005 Wombat Web Bench
    @link http://wombat.exit0.net
    @package wombat
    @subpackage manual
    
**********************************************************

INSTALLATION
============

1) Get Wombat
There are several options to get Wombat.
  - from Subversion Repository
  - from archive like tar.bz2 or zip
  - as debian package
  - as PEAR package ?

Well, actually, there is only one way to get Wombat - which makes it an
easy choice. :-(

1.1) Get Wombat from the Subversion Server
The repository is located at:
    https://gerd.exit0.net/svn/wombat

The current developing version can be found in "trunk". If you prefere to
download a taged version or a special branch - those can be found in "tags"
respective "branches".

Let's say you are living on the edge, hence you want to play with the latest
developing version of wombat. Then go to the directory of your choice (e.g.
your private public_html folder woulb be a good choice) and checkout Wombat. 

Linux users may want to enter some command lines:

    $ cd ~/public_html
    $ svn checkout https://gerd.exit0.net/svn/wombat/trunk wombat

Windows users must perform a combibation of left and right clicks to reach
a point where they can enter the URL mentioned above. :-)

2) Make sure!
If this is the first time you install Wombat, you should keep it simple and
stupid (KISS). In other words, you will run the framework AND the concrete
site in the same directory. This is how Wombat comes out of the box.

Still, a few things need to be arranged or at least, make sure, that they are
already arranged properly.
  - check file ownership and permissions
  - run Wombat make

2.1) Check Permissions
The wrong file permissions will result in errors, because Wombat needs write
access to some files and folders. Well, checking file permissions and ownership
can be a mess, but Wombat framework comes with a tool that does most things for
you: wombatmake.

Still, you must own the whole directory tree and all the files and folder must
be writeable by you! Usually, this is the case anyway. If not, the following
commands may help:

  Change ownership of files - this mey only be done by root!
    $ chown -R <user>:<group> wombat

  Add write permissions for owner
    $ chmod -R u+rw wombat

  Allow user to enter directories
    $ find wombat -type d -exec chmod u+x {} \;
    
Wombatmake can be found in "bin/wombatmake". As a script, it must be marked as
exeutable, as well. If this is not the case, add X-flags with:

  Add executable flag to wombatmake
    $ chmod u+x wombat/bin/wombatmake

There is also a batch-file for Windows users, called "wombatmake.bat". As Windows
uses the file-extension ("bat" in this case) to decide whether a file is exeutable,
this file don't need special permissions.

2.2) Run Wombat Make
The make tool is located in bin/wombatmake. It is a PHP-CLI-Script and supposed
to be executed as such. Windows users may want to execute bin/wombatmake.bat
instead. If you don't have PHP-CLI, you can also use the web-frontend of Wombat Make.
Unfortunatly, the web frontend is not written, so far... :-(

2.2.1) Linux users
Before you run wombatmake, check the php-executable's path and adjust the first line
of wombatmake, if neccesary.

  Where is php's binary?
    $ type php
    php is /usr/bin/php

  Check wombatmake's first line
    $ head -n 1 wombat/bin/wombatmake
    #!/user/bin/php

  Now run wombatmake
    $ wombat/bin/wombatmake --help

  Or just select a proper target
    $ wombat/bin/wombatmake install

    
2.2.2) Windows users
The good news is: Windows users usually don't have to muck around with file
permissions. The bad news is, the running webserver may be able to read or write
any file. And the worst news is: Any stupid, damned PHP script may harm the whole
server - either by accident or purpose.

Still, it is recommended to use wombatmake, respective wombatmake.bat. As the
batch-file is fairly simple (it basicly calls wombatmake), it shouldn't be a drama,
if it does not work. A common problem may be, that PHP (php.exe) is not in %PATH%.
To solv this problem, adjust %PATH% or the batch-file. If both don't suit your needs,
just call wombatmake with php:

  Call wombatmake with php
    C:\www\wombat> php.exe bin/wombatmake

3) Switch debugger on
As long as you are testing and developing your site, the build in debugger prints
some useful information. If the debugger is off, you won't see anything.

To switch on debugging features edit conf/config.php:                                                   

  conf/config.php
  -------------8<-------------8<-------------8<-------------8<------------
  // switch debugger on
  wbFactory::setParam( 'debug', 1 );    
  -------------8<-------------8<-------------8<-------------8<------------

4) Test surf
Use your prefered browser and surf to the loaction where you expect wombat.
As long as you stick to the "out-of-the-box" settings, the web site can found
in wombat/htdoc

The index.php will display a very simple and ugly test page! If debugger is on,
there will be some debugging messages at the bottom of the page.

5) Do whatever you want.
Now, the framework is up an running, but there is still heaps to do. What is left,
is all this site-specific stuff:

 - create your page layout/design
 - create templats and add images, style-sheets  etc to wombat/htdoc
 - adjust site config
 - fill in content; add pages

 
Optional there is more
 - Use some modules
 - Setup the administration area - or get rid of it
 - implement site special extensions
 - create additional layouts
 - read the fine manual :-)

More information about configuration and customisation can be found in the 
direcoty "config"