           _- __   
       || _-_-- -__ 
       || //  --   
    _  ||//                  
 --__- ||/                
    -\\||               
      \||                
       ||                     
 
   B A M B O O   
   ^ ^ ^ ^ ^ ^   

- pretty urls (site.org/path/to/page/)
- integrated search
- multiple user backends, easy to extend.
- support for pages of wiki-like markup, html, or php.
- upload attachments to any page.

REQUIREMENTS
============

- php 4.3 or newer
- sqlite (optional)
- file (optional)

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

for example, to install bamboo for a site at www.domain.org/blue.

1) install required packages:
   # apt-get install apache php4 php4-sqlite sqlite file

1) Untar bamboo as /var/www/bamboo.
   You can also use /usr/local/share/bamboo or /usr/share/bamboo,
   but this readme will use /var/www/bamboo in the examples. If the
   bamboo lib directory is not browseable as /bamboo, make sure to
   set the correct value in b.site for 'liburl'. 

2) Create site root directory, and make it so it is writable by the
   group the webserver is running as:
   # mkdir /var/www/blue
   # chgrp www-data /var/www/blue
   # chmod 775 /var/www/blue

3) Create a site property file
   The site property file b.site specifies vital info about the site
   and lives in the site root directory. In our example, the
   site property file would be "/var/www/blue/b.site".

   A b.site example:
     siteroot = /blue
     sitename = test site
     userbackend = static, myuser:mypassword

   If your site was browsable as blue.org instead of domain.org/blue
   you would make 'siteroot' equal to '/' instead. The simplest of user
   backends is 'static' in which you hardcode a single user and password
   in the b.site file. See below for more information on user backends.

   The only required property is siteroot, but there are many important
   options. See DOCS/b.site for details the options.

3) configure apache

httpd.conf:
  Alias /bamboo/ /var/www/bamboo

.htaccess (ie /var/www/blue/.htaccess)
  ErrorDocument 404 /bamboo/frontdoor.php
  DirectoryIndex index.html index.php /bamboo/frontdoor.php
  Options -Indexes
  <Files "b.*">
    Deny from all
  </Files>
   
or, in httpd.conf:
  <directory /var/www/blue>
    ErrorDocument 404 /bamboo/frontdoor.php
    DirectoryIndex index.html index.php /bamboo/frontdoor.php
    Options -Indexes
    <Files "b.*">
      Deny from all
    </Files>
  </directory>

or, for blue.domain.org:  
  <VirtualHost *>
    ServerName blue.domain.org
    DocumentRoot /var/www/blue
    ErrorDocument 404 /bamboo/frontdoor.php
    DirectoryIndex index.html index.php /bamboo/frontdoor.php
    Options -Indexes
    <Files "b.*">
      Deny from all
    </Files>
  </VirtualHost>                

If bamboo is not aliased to /bamboo, make sure you set 'liburl'
in b.site. It is very important that you block access to files
with "b." at the start. Otherwise, permissions are useless.

AUTHENTICATION
==============

  *******
  NOTE: only 'static' and 'file' user backends are distributed
  with this release, more to come soon.
  *******
  
For authentication, you can choose from among many user backends, or add 
your own:

(1) sqlite -- store users in a local sqlite database file
              (this is the default and is recommended).
(2) static -- a single static user defined in b.site (read only).
(3) file   -- store users in a passwd like file (read only).
(4) mysql  -- store users in any mysql database.
(5) ldap   -- store users in a ldap directory.
(6) apache -- let apache handle the authentication.

User backends live in /var/www/bamboo/userstores. To create a backend
"crow", you would create the class userstores/CrowUserStore.php.

Backend "sqlite":
  Edit b.site like so:
    userbackend = sqlite, path/to/database
  if empty, the database defaults to ./.bamboo/users.sqlite

Backend "static":
  Edit b.site like so:
    userbackend = static, myuser:$1$SPoaSG1n$23eLey961a6LF67RNr5RH/
  The password can be clear text or crypt_md5 hash (see below).

Backend "file":
  Edit b.site like so:
    userbackend = file, path/to/b.users
  The file specified could be an absolute path or relative to the site root.
  The format is "username:password". The password can be clear text or
  crypt_md5. Here is an example b.users:
    user1:$1$SPoaSG1n$23eLey961a6LF67RNr5RH/
    user2:this-is-a-cleartext-passwd
  crypt_md5 hashed passwords can be created with:
    # apt-get install whois 
    > mkpasswd --hash=md5
  or
    # apt-get install php4-cli
    > php4 -r 'echo crypt("my password","$1$".md5(time())) . "\n";'
      (the md5(time()) is just to get a random salt).

Backend "mysql":
  not yet working
  
Backend "ldap":
  not yet working
  
Backend "apache":
  not yet working


PERMISSIONS
===========

Currently, there are only two permissions which matter:
access-view and access-edit. The interface does not provide
a method to set these yet.

For now, to change the permissions for a branch of the tree,
edit the file b.inherit for the page. For example:

/var/www/blue/private/b.inherit:
  access-edit = user1
  access-view = anonymous

This will limit editing access to page 'private' (and all
sub pages) to user 'user1'. These may also be set in
b.site.

