=pod

=head1 Installing a Nebulous Server

=head2 Create a UNIX group for Nebulous

    groupadd -g 877 nebulous

This is a silly hack to generate a gid.

    perl -le 'map { $gid += ord } split //, shift; print $gid' nebulous

=head2 Add the users that you want to be able to access Nebulous to that group

    usermod -G nebulous foouser

=head2 Build and install the Nebulous Perl modules (see: README)

=head2 Create and initialize the database (see: docs/database_setup.txt)

=head2 Install Apache with mod_perl

Nebulous will work with both Apache 1.3 & 2.x.

=head3 Apache 1.x 

=item * building mod_perl-1.29 from source:

    perl Makefile.PL USE_APXS=1 INSTALLDIRS=vendor WITH_APXS=/usr/sbin/apxs EVERYTHING=1 PERL_DEBUG=1

    #MP_TRACE = 1 MP_DEBUG = 1 MP_USE_DSO = 1 MP_INST_APACHE2 = 1 MP_APXS = /usr/sbin/apxs2

=head3 Apache 2.x 

To use Nebulous with Apache2 you must have Apache2 >= 2.0.54 and mod_perl >=
2.0.0

Apache::DBI >= '0.97' is required for connect_on_init() to work under mod_perl >= 2.0.1

=head4 removing Apache on RHEl3

As C<root>:

    rpm -e \
    httpd-2.0.46-46.2.ent \
    httpd-devel-2.0.46-46.2.ent \
    redhat-config-httpd-1.1.0-4.30.2 \
    mod_perl-1.99_09-10.ent \
    mod_authz_ldap-0.22-5 \
    mod_auth_pgsql-2.0.1-4.ent \
    mod_python-3.0.3-5.ent \
    mod_auth_mysql-20030510-2.ent \
    mod_ssl-2.0.46-46.2.ent \
    webalizer-2.01_10-15.ent \
    mod_perl-1.99_09-10.ent \
    mod_auth_pgsql-2.0.1-4.ent \
    mod_python-3.0.3-5.ent \
    mod_auth_mysql-20030510-2.ent \
    mod_ssl-2.0.46-46.2.ent \
    squirrelmail-1.4.3a-11.EL3 \
    php-4.3.2-25.ent \
    php-imap-4.3.2-25.ent \
    php-ldap-4.3.2-25.ent \
    php-mysql-4.3.2-25.ent \
    php-odbc-4.3.2-25.ent \
    php-pgsql-4.3.2-25.ent 

    rm -rf /etc/httpd

=head4 installing Apache2 from source

    tar -jxvf httpd-2.0.54.tar.bz2
    cd httpd-2.0.54
    ./configure \
    --disable-suexec \
    --with-perl=/usr/bin/perl \
    --with-port=80 \
    --with-program-name=apache2 \
    --with-devrandom=/dev/urandom \
    --prefix           /usr \
    --exec_prefix      /usr \
    --bindir           /usr/bin \
    --sbindir          /usr/sbin \
    --libdir           /usr/lib \
    --libexecdir       /usr/lib/apache2/modules \
    --mandir           /usr/share/man \
    --infodir          /usr/share/info \
    --includedir       /usr/include/apache2 \
    --datadir          /var/www/localhost \
    --sysconfdir       /etc/apache2/conf \
    --localstatedir    /var
    make
    su
    make install
    exit
    cd ..

    tar -zxvf mod_perl-2.0.1.tar.gz
    cd mod_perl-2.0.1
    perl Makefile.PL
    (apxs = /usr/sbin/apxs)
    make
    su
    make install
    echo "LoadModule perl_module /usr/lib/apache2/modules/mod_perl.so" >> /etc/apache2/conf/apache2.conf
    exit

    apachectl configtest
    Syntax OK

=head3 Common Apache Setup

=item * add the "nebulous" group to /etc/group
=item * configure Apache to run as the nebulous group. 


# out of date from here down...

#
# CGI interface
#

ScriptAlias /nebulous /usr/local/apache/perl/imageserver.pl

<Directory "/usr/local/apache/perl">
        AllowOverride None
        Options None
        Order allow,deny
        Allow from all
</Directory>

PerlModule Apache::PerlRun
<Location /perl>
        SetHandler perl-script
        PerlHandler Apache::PerlRun
        Options ExecCGI
        allow from all
        PerlSendHeader On
</Location>

#
# Nebulous::Apache interface
#

PerlModule Apache::DBI
PerlModule Nebulous::Apache

<Location /nebulous>
        SetHandler perl-script
        PerlHandler Nebulous::Apache
</Location>

- setup the server

As a CGI, will with either Apache 1.3.x or 2.0.x

cp scripts/imagesever.pl /var/www/localhost/cgi-bin
chmod 755 /var/www/localhost/cgi-bin/imageserver.pl
touch /tmp/imageserver.log
chmod 1777 /tmp/imageserver.log

=head2 Testing the Nebulous Server

You can test your configuration with the C<telnet> utility.

    telnet localhost 80
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is '^]'.
    GET /cgi-bin/imageserver.pl HTTP/1.0

    HTTP/1.1 411 Length Required
    Date: Tue, 28 Sep 2004 21:15:58 GMT
    Server: Apache/2.0.49 (Gentoo/Linux)
    Content-Length: 0
    Connection: close
    Content-Type: text/plain; charset=ISO-8859-1

    Connection closed by foreign host.

If you get an HTTP 5xx code check your apache error_log

=head2 Directory Permissions

    mkdir /po01/nebulous
    chown root:nebulous /po01/nebulous
    chmod 0770 /po01/nebulous

=head2 MySQL Configuration

in /etc/mysql/my.cnf
under [mysqld]
increase the number of alloweed connections, e.g.
max_connections = 200

=cut
