####
#### NOTICE
#### 
#### Likely, by ApacheCon US 2006 (Texas) in october, infra@ will have 
#### abolished minotaur.apache.org and helios (SunOS) will be running
#### people.zones.apache.org.

#### has host specific conigs we will need to update:
####    bin/site_build 
####    bin/makeindex 
####

This docco explains how to update perl.apache.org

The site is being anonymously checked out and built under
/home/perlwww/apache.org/modperl-docs and then synced into
/www/perl.apache.org. user 'perlwww' is in the 'perl' group, so
whatever it creates you should be able to modify at will. All the
files under /home/perlwww are made g+rwx to group 'perl', so you can
mess with files without becoming 'perlwww'.

*** sudo'ing to perlwww ***

Sometimes you need to sudo into the 'perlwww' user, to perform things
that only that user can do (e.g. modifying crontabs).

To sudo into the 'perlwww' user (assuming that you have the perms to
do so):

To avoid annoying root with e-mails, you can use the -l flags to
see if you have the perms.

sudo -l
User xxxx may run the following commands on this host:
    (perlwww) NOPASSWD: ALL

sudo -H -u perlwww bash

or:

sudo -H -u perlwww tcsh

*** Automatic Updates ***

The site is being updated automatically from the crontab. So all you
have to do is to commit your changes and wait for them to be picked up
by the update system.

This is the current crontab

% crontab -l
MAILTO=docs-dev@perl.apache.org

# every monday rebuild all, including pdf
30 03  * * 1 /home/perlwww/apache.org/modperl-docs/bin/site_build_force_pdf_index
# update all (only changes/no pdf) every 6 hours
15 6,12,18 * * * /home/perlwww/apache.org/modperl-docs/bin/site_build_index
# update all (only changes and pdfs) once a day
15 0 * * * /home/perlwww/apache.org/modperl-docs/bin/site_build_pdf_index

In order to modify the crontab you must sudo into the 'perlwww'
user. Notice that everyone in the 'perl' group can modify the crontab
which is the main reason for creating this special user.

If the updating script emits any warnings/errors, they will be sent to
the email address listed in /home/perlwww/.forward.  Currently,
docs-dev.

*** Manual Updates ***

If for some reason you cannot wait for the automatic update
(e.g. if you've changed the template and don't want to wait a week for
the update to be picked up) there a few symlinks that you can use to
update the site:

/home/perlwww/apache.org/modperl-docs/bin/site_build                      
/home/perlwww/apache.org/modperl-docs/bin/site_build_index
/home/perlwww/apache.org/modperl-docs/bin/site_build_force                
/home/perlwww/apache.org/modperl-docs/bin/site_build_pdf
/home/perlwww/apache.org/modperl-docs/bin/site_build_force_index          
/home/perlwww/apache.org/modperl-docs/bin/site_build_pdf_index
/home/perlwww/apache.org/modperl-docs/bin/site_build_force_pdf_index

if the name includes:
force - the whole site is rebuilt
pdf   - builds pdfs
index - builds the index

the more you ask to do, the longer it will take the update. e.g.,
site_build only updates the html files, if you use site_build_index
the search index will be updated as well, site_build_pdf will update
htmls and pdfs, etc. site_build_force_pdf_index does a complete
rebuild of htmls, pdfs and the search index.

In most cases, when you do a minor update you just need to run:

  /home/perlwww/apache.org/modperl-docs/bin/site_build

so it'll rebuild the html of the modified files.

*** Full filesystem ***

When the /www/ fs is full and we attempt to copy files over it, the
whole online version may get rendered broken, since some (all) files
will be simply truncated to 0. so the script takes care of checking
whether the available space on the filesystem is at least 50MB bigger
than the size of the site, and if not, the online version of the site
won't be updated.

*** Resolving Problems ***

If the problem is with the build system email the docs-dev list. If
the problem with the apache.org machine email root@apache.org.