This document describes how to install a new Verdad installation, and how to deploy new copies of the Verdad code onto the installation.
You need an Apache webserver configured with mod_perl. You also need an MySql database, which should be on the same machine. (This is the only tested configuration, though splitting the webserver and the database should work.) Verdad is developed using Apache 1.3.14, mod_perl 1.24_01, and MySql 3.23.32.
You will also need several Perl modules installed. See the ``Get Your Perl to Not Suck'' section.
These directions also assume you'll be using a virtual host
on your webserver. Even if this machine is dedicated to Verdad,
you should use the virtual host, to simplify writing and
reading these directions. For example, at Tellme, we arranged
for verdad.villa.tellme.com to point to the actual server,
verdad01.villa.tellme.com by making a CNAME in DNS.
Name-based virtuals work OK.
There's no reason to go to the effort of assigning
virtual IP addresses.
The example config files in this document assume a certain layout for files and directories. Your mileage may vary.
All the good stuff is in non-standard modules these days. It's not just enough to install Perl and walk away. A Perl install is really only useful once it has these extra modules:
DBI
DBD::mysql
Parse::RecDescent
MIME::Base64
URI
ApacheDBI
Net::FTP
LWP
Time::HiRes
You can get these by starting up the CPAN.pm shell like this:
perl -MCPAN -eshell
then answering the incessant questions, then typing ``install Module''. If you need more help with CPAN.pm, please seek it on the net.
Put Verdad on the machine in /usr/local/verdad. You could probably choose another place for it, if you adjust these instructions correctly. However, if you do that, it will be harder for other people to help you, so consider doing it like the rest of us, please.
The Verdad package expects MySql to be configured as follows:
root user has no password, but only allows access from localhost
If you are CERTAIN you agree with these permissions and are ready to have your mysql database configured that way for you, then do this:
$ cd /usr/local/verdad/sql
$ mysql -u root -p < grant-root.sql
If you currently have no root password, then you should omit the
-p in the last line above.
If you disagree with this policy, some things won't work right until you edit the script and/or Makefile and hardcode your root password into it. Just don't use a ``real'' password, since it's guaranteed to be compromised when you go around putting it into files. This is why the default configuration uses no passwords. Passwords put into files are worse than none at all, since if you use a ``real'' password, then you'll be tempted to put it in a file, and then you're guaranteed to compromise it sometime.
As for user accounts, Verdad requires the following:
verdad user with no password exists and has full access to
database verdad
backup user with no password exists and has limited access to
database verdad
To make that happen, do this:
$ cd /usr/local/verdad/sql
$ make grants
If you disagree with the suggested policy of not having passwords for these users, you are welcome to do something different. Remember, though, that if you assign passwords, you should use ones that are not used anywhere else, since you will be putting them into scripts. Also, consider that you'll need to hand-edit some scripts again every time a new Verdad release comes out. Make your life easier; don't use database passwords.
IMPORTANT: The policy of ``No Database Passwords'' advocated here
is ONLY appropriate if only trusted users are able to login
to server running the MySql process.
If you can't trust the users on that machine,
you'll need to use passwords. Or consider getting new users...
:)
Now, you need to create a database named ``verdad'' in your MySql server. Do this:
$ cd /usr/local/verdad/sql
$ make db
And load the schema into the database:
$ make load-schema
If you want the default install, you can do it all in one go with:
$ make init
Now, go find your web server's config file. Edit it to add something like this to the end:
PerlInitHandler Apache::StatINC
PerlRequire conf/startup.pl
PerlFreshRestart On
Include conf/virtuals
That says that we'll be loading a Perl file on boot, that
we want restarts to reinit Perl, and that we want to read
each file in the directory conf/virtuals and
integrate it into the configuration file as though they
were all included. There's nothing magical about the name
virtuals; it just so happens that we'll only be putting files
in here that define virtual servers. This setup is not
Verdad-specific; it's just a suggestion for a way to set
things up the has proven to scale nicely when there are lots
of virtual servers on one machine.
Now, put something like this into conf/startup.pl:
#!/usr/local/bin/perl -w
use strict;
use Apache::Registry();
use Apache::Constants();
use CGI qw(-compile :all);
use CGI::Carp();
use Apache::DBI;
1;
The point of this file is to load modules that the entire webserver, and all the virtual servers will find useful. This happens once at server boot time instead of in every child, and saves memory and CPU.
Now, put a file in conf/virtuals named the same thing
as the CNAME you assigned for your virtual server. This will
hold something like the following, though you'll need to change
at least the first 5 lines to suit your site:
<VirtualHost *>
ServerName verdad.villa.tellme.com
ServerAlias verdad.villa
ErrorLog /var/tellme/verdad.villa.tellme.com/logs/error_log
CustomLog /var/tellme/verdad.villa.tellme.com/logs/access_log common
DocumentRoot /var/tellme/verdad.villa.tellme.com/htdocs
<Location />
Options Indexes
Order allow,deny
Allow from all
AuthType basic
AuthName "Enter your Verdad username and password."
AuthUserFile "/etc/verdad-passwd"
</Location>
PerlRequire /usr/local/verdad/web/perl/startup.pl
<Location /perl>
SetHandler perl-script
PerlHandler Apache::Registry
PerlSendHeader On
Options Indexes ExecCGI
Require valid-user
</Location>
<Location /perl-public>
SetHandler perl-script
PerlHandler Apache::Registry
PerlSendHeader On
Options Indexes ExecCGI
</Location>
Alias /icons/ "/usr/local/icons/"
<Directory "/usr/local/icons">
Options Indexes MultiViews
AllowOverride None
Order allow,deny
Allow from all
</Directory>
</VirtualHost>
Arrange for the DocumentRoot to point at the stuff in /usr/local/verdad/web, either by copying the web content under the DocumentRoot, or via a symlink.
The /etc/verdad-passwd file should be created and populated using htpasswd. Here are some example commands:
# to create the file
htpasswd -c /etc/verdad-passwd jra
# subsequent users
htpasswd /etc/verdad-passwd sam
Once again, by loading the startup.pl file that Verdad provides, you parse the Verdad modules once in the parent, which is a Good Thing (tm).
The lines above related to authentication are examples. They need to be customized for how you want to handle authentication.
Stop and start your webserver and see if it works. If not,
look carefully at the logs/error_log and the
server-specific error_log specified in the VirtualHost
section for your server.
You should be able to navigate to a URL like:
http://verdad.villa.tellme.com/
and see Verdad's opening page.
You can now start adding items to your database and then look at them and work with them using the web user interface.
Jeff R. Allen <jra@nella.org>