Web Man Files

===========================================================================
                            Web Man Read-me File
===========================================================================

Introduction: What is Web Man?
------------------------------
  Web Man is a web site that manages other webs on the server with it.
The user points a browser at Web Man, then interacts with its pages. These
pages have forms with buttons and JavaScript event handlers that call Perl 
scripts by AJAX. These scripts do the actual work on the server: moving pages, 
editing the site map, installing navigation bars, applying templates, 
checking links, applying style sheets, etc.
  Web Man is designed to run on a workstation that also has an Apache web 
server running. It can also run on a remote server, but is probably not secure
there in its current alpha form. Such a setup allows a Windows or Mac user
to run Web Man from her workstation as a client.
  See the bottom of this file for notes on the current release.

====================
Web Man Installation
====================

System requirements
-------------------
  o Linux. Ubuntu is a fine platform for Web Man; many other Linux 
distributions will probably work.
  o Apache 2 or 2.2, Perl 5.
  o FireFox under any OS for the client.

Recommended
-----------
  o Perl modules Log::Log4per, HTML::Tree, HTML::TreeBuilder, HTML::Element. 
Other needed modules probably came with Apache. Substitute modules are
provided as webmann/cgi-bin/WMlogger.pm.simple, and in the directory
webmann/cgi-bin/HTML. These paths are relative to the directory in which the
distribution tarball is extracted.

Meaning of directory and file name variables
--------------------------------------------
  You will need these for manual or script installation, but don't do anything 
to your files just yet. You are planning your Web Man environment here. Write
down your decisions.
  These names are used in Apache's configuration files, also in Web Man's
documentation and sources. Their actual values can be set by the installer 
script or manually.

  DocumentRoot          Absolute path, same as Apache DocumentRoot
  WorkSpace             Absolute path to webs managed by Web Man
  WMRoot                Path to Web Man's own web
  WebList               Path to list of most recently managed webs
  WMLogs                Path to logs of what Web Man did
  WMScripts             Path to Web Man's scripts. They may move.
  User                  User in Apache configuration. Owns webs and scripts.
  Group                 Group in Apache configuration.

  WMRoot, WebList and WMLogs are relative to DocumentRoot. WMScripts is 
relative to Apache's ScriptAlias, or relative to DocumentRoot. All paths 
except WebList are directory paths. Directories need trailing slashes.

Planning Web Man's environment
------------------------------
1.  Find DocumentRoot in your Apache environment. In Apache configuration 
files, DocumentRoot is the directory from which Apache serves all webs, 
including Web Man. It is an absolute path.
  This defaults to /var/www/.
2.  Decide on a directory for the webs Web Man manages. That is WorkSpace, 
another absolute path.
  WorkSpace defaults to /var/www/wmspace/workspace/.
3.  WMRoot is Web Man's own web site. It must be at or below DocumentRoot, but
does not have to be at or below WorkSpace. If it is, Web Man can manage
itself. If WMRoot is up outside of WorkSpace, it will not be able to manage
(or damage) itself. This path is relative to DocumentRoot. 
  WMRoot defaults to /wmspace/webmann/.
4.  WebList is a list of the webs most recently managed by Web Man. It must
go immediately in WMRoot. This is a file path, so needs no trailing slash. It
is relative to DocumentRoot.
  WebList defaults to /wmspace/webmann/wmwebs.list.
5.  WMLogs contains Web Man's logs. It is relative to DocumentRoot. This
directory is created empty when the distribution tarball is extraced.
  WMLogs defaults to /wmspace/logs/.
6.  WMScripts could be in two very different places, depending on whether you
want Web Man's CGI scripts in Apache's preferred location ScriptAlias, or
want to keep them in Web Man's own web.
  If you want them where Apache expects them, you will have to move them 
there. The install script is prepared to do that. In that case, WMScripts
defaults to /cgi-bin/wmscripts/.
  If you keep them where they are, you will have to change Apache's 
configuration. The install script is prepared to do that. WMscripts will then 
default to /WMRoot/cgi-bin/, relative to DocumentRoot.
7.  The User and Group do not have to be configured; Apache already has them.
Webs and scripts must be owned by Apache's User and Group. The install script 
will first guess what they are, then ask the installer what they are. Later it 
will change ownership of webs and scripts accordingly.
  User and Group both default to the owner and group of DocumentRoot.

Extracting the installation files
---------------------------------
1.  Put the wmspace.bz2 tarball in DocumentRoot or some directory below it.
Remember where this installation directory is.
2.  Untar wmspace.bz2 with 

$ tar xjf wmspace.bz2

  That will create 3 webs, one empty directory, and two files:

  workspace/fpsite     A test Front Page (TM) web
  workspace/wmsite     A test Web Man web
  webmann              Web Man, itself a web
  logs                 Where Web Man writes logs as plain HTML
  readme.txt           A copy of this readme
  wm_install.pl        The installer script

==========================
Using the Installer Script
==========================

  Run perl wm_install.pl it as root, or a user able to write on DocumentRoot.
  When the script runs, it will ask a series of questions with default replies.
Hit <Enter> to accept the defaults, or enter your own replies. Some of those
may mean that the script will have to move files or directories other than the
scripts.
  You will have a chance to see the changes to your files and directories be-
fore committing to an installation.

===================
Manual Installation
===================

Configuring Apache
------------------
1.  If you want Web Man's scripts to stay where the distribution tarball
puts them, configure /WMRoot/cgi-bin as an Apache <Directory>. Skip this 
section if you plan to move the scripts to ScriptAlias or below.
  In the Debian world, configuring a script-capable <Directory> means
making one file /etc/apache2/sites-available/webmann. With other Apache 
layouts, you might add to httpd.conf or some other configuration file. Here's 
an example, following the example environment above:

#  Web Man, the website manager

<Directory /var/www/wmspace/webmann/>
  Options +Includes +ExecCGI
  AddHandler cgi-script .cgi .pl
</Directory>

  It needs +ExecCGI and +Includes. Those may be already enabled at wider scope.
If not, Web Man cannot run its scripts.
  It needs AddHandler cgi-script .cgi .pl. That may be already enabled at 
wider scope.
  It probably doesn't need AddOutputFilter INCLUDES .shtml. Usually, that is 
already enabled in mod_mime.
  The install script is prepared to add that to httpd.conf if the installer
approves.
2.  Enable the webmann site if necessary (Debian: use a2ensite). Restart 
Apache. The installer script will offer to do the restart, but does not offer
enabling the webmann site. It prefers to add it to httpd.conf, so no special
Debian enabling is necessary.

Installing Web Man's web site and scripts
-----------------------------------------
1.  If you don't want to change your Apache configuration, move Web
Man's scripts to Apache's ScriptAlias directory or below. That means you are
implementing your planned WMScripts. The installer script will offer to do
that.
2.  Check permissions for CGI scripts in WMScripts: they need to be 744.
Modules can be 644. The current release should have this correct. Releases 
0.02 and earlier did not. The installer script will offer to do that.
3.  Check ownership for everything in the installation directory: it must all
belong to Apache's User:Group. The installer script will offer to do that.

Configuring Web Man
-------------------
1.  Open WMScripts/WMtools.pm in an editor.
2.  Find WMtools::WMENV. Adjust as necessary to fit your planned environment.
The installer script will show the adjustments, and offer to implement them.
3.  Edit WMRoot/js/wm.js. Find document.env and adjust it. This defaults to 
/cgi-bin/wmscripts/getEnv.cgi, and assumes the scripts will be moved into or
below ScriptAlias. In your environment, this is WMScripts + 'getEnv.cgi'. See 
WMtools::WMENV. The installer script will offer to make that change to wm.js.
4.  If Log::Log4perl is not in your Perl modules, you can use Web Man's 
supplied replacement. Copy WMScripts/WMlogger.pm.simple onto 
WMScripts/WMlogger.pm. Or, you can run CPAN and install Log::Log4perl.
If you do that after installation, you can get better logging by copying 
WMScripts/WMlogger.pm.Log4 onto WMScripts/WMlogger.pm.
5.  Point your browser to WMroot. Web Man should present its main editing
page, as in the screen shot at http://sourceforge.net/projects/webmann/.

==================================
Web Man Release Notes for alpha006
==================================

* Simplified installation: Web Man, two sample webs, empty log directory,
install script and this readme.txt all come in one tarball.
* The install script can do a complete installation. This guide covers its use, 
and manual installation.