Beehive's Live Documentation Site
---------------------------------

The following instructions explain how to maintain the Beehive's live documentation.

The site is currently posted at 

  http://incubator.apache.org/beehive.  

When Beehive leaves incubation, the address will change, in all probability, to 

  http://beehive.apache.org/ 

The main site address, http://incubator.apache.org/beehive, should display
the docs for the latest release.

Upcoming releases may be posted in an appropriately named sub-directory.  
For example, an upcoming ver.-whatever-beta release should be posted at 

  http://incubator.apache.org/beehive/v-whatever-beta

Posting of upcoming release docs is primarily for developer review of the forthcoming docs.


Requirements for Updating the Live Site
---------------------------------------

To update the live site, you must have the following three software installations:

  (a) a Beehive SVN enlistment (See beehive/trunk/BUILDING.txt)
  (b) a SCP (Secure file CoPy) client installed on your machine
  (c) a SSH (Secure SHell) client

The following instructions assume that you have the Putty SCP and SSH clients installed.
(Downloadable from http://www.putty.nl/download.html) 
If you have different clients, the instructions can be easily modified to work with 
that client (using a bit of common sense).  For example, you could easily replace
the SCP client with a SFTP (Secure File Transfer Protocol) client.

Before proceding, it is important that your umask (on
people.apache.org) is set to "0002" so that group write is set on the uploaded
ZIP file.  This insures that there are no permissions problems, 
if someone else performs the next site update.  

Note, however, a umask setting of 0002 will *not* affect the files extracted from the ZIP file!
This is because files extracted via UNZIP do not have group-write permission by default!
You must change the permissions on this extracted files manually!  See step (4) for details. 

Process for Updating the Live Site
---------------------------------------

In brief, the process for updating the live site goes as follows:

  (1) Make a ZIP file of the latest docs on your local machine.
  (2) Upload the ZIP file to the remote (live) machine.
  (3) Unzip the ZIP file on the remote (live) machine.
  (4) Change the unzipped files to allow group-write permissions!

(1) Make a ZIP file of the latest docs
--------------------------------------

Run the following Ant command (assuming that your shell is pointed at the 'beehive/trunk' directory):

  ant -f distribution.xml clean.dist build.dist.docs build.livesite

This will build a ZIP file called "site.zip" and save it at 

  /beehive/trunk/build/dist/archives/site.zip

Note: this ZIP file has *no* top-level directory.  If you unzip it, it will 
spew files all over the directory you unzip it into.  For this reason, you should 
take care where you unzip it.  

*Why* does it have no top-level directory?  
Because it is much easier to manage the URL for the live site, if the ZIP file has no 
URL-determining elements (such as a top-level directory) in it.

(2) Upload the ZIP file to the live, remove machine
---------------------------------------------------

cd to 

  /beehive/trunk/build/dist/archives

Run the following commmand:

  pscp -pw [password] site.zip [username]@people.apache.org:/www/incubator.apache.org/beehive/[target_dir]

  [password] - your password on cvs.apache.org
  [username] - your username on cvs.apache.org
  [target_dir] - the directory where you want the site.zip to go.  
     This could the empty string, especially if you are updating 
     the main live site for a major release of Beehive.

(3) Unzip the ZIP on the live, remote machine
---------------------------------------------

Using the SSH client, make a connection to cvs.apache.org.

  cd to /www/incubator.apache.org/beehive/[target_dir]

  unzip site.zip

If the directory already contains content, you will be asked to confirm the overwrite.  

The content is now live!

Note that overwriting the contents of the directory is *not* the same as deleteing all content
from that directory.  If there is old content to be deleted that is not covered by the 
overwrite, you must manually delete it. 

For example, to recursively remove the all contents of the directory 'foo', use the 
following command: 

  rm -r foo  

To ignore write-protection in the directory, use: 

  rm -r -f foo

Obviously: be careful when deleting content from the site!

(4) Change the unzipped files to allow group-write permissions
--------------------------------------------------------------

After you have unzipped the files, the permissions on the 
unzipped file is: 

  -rw-r--r-- 

which doesn't allow other users to overwrite the unzipped file.

Execute the following command 
to change the file permissions to group-write:
  
  chmod -R 775 .

This will change file permissions on every file in the directory to:

  -rwxrwxr-x

If you don't do this, no one else will be able to upload and unzip the live site!