=head1 Guide's Overview

=head1 What's inside?

Before you start a mod_perl installation, you should have an
overall picture of this wonderful technology. There is more than one
way to use a mod_perl-enabled webserver. You have to decide which
mod_perl scheme you want to use. L<Picking the Right
Strategy|strategy/> chapter presents various approaches and discusses
their pros and cons.

Once you know what best fits your requirements, you should proceed
to L<Real World Scenarios Implementation|scenario/>.  This chapter
provides very detailed scenarios of the schemes discussed in the
L<Picking the Right Strategy|strategy/> chapter.

The L<Server Installation|install/> chapter follows on from the L<Real
World Scenarios Implementation|scenario/> chapter by providing more
in-depth installation details.

The L<Server Configuration|config/> chapter adds to the basic
configurations presented in the L<Real World Scenarios
Implementation|scenario/> chapter with extended configurations and
various configuration examples.

The L<Frequent mod_perl problems|frequent/> chapter is a collection of
links to other chapters. It is an attempt to stress some of the most
frequently encountered mod_perl problems. So this is the first place
you should check if you have got a problem.

Probably the most important chapter is L<CGI to mod_perl
Porting. mod_perl Coding guidelines|porting/>. It explains the
differences between scripts running under mod_cgi and mod_perl, and
what should be done in order to make existing scripts run under
mod_perl. Along with the porting notes it provides guidelines for
proper mod_perl programming.

L<Performance. Benchmarks|performance/> is the biggest and a very
important chapter. It explains the details of tuning mod_perl and the
scripts running under it, so you can squeeze every ounce of the power
from your server. A large part of the chapter is benchmarks, the
numbers that IT managers love to read. But these are different
benchmarks: they are not comparing mod_perl with similar technologies,
rather with different configurations of mod_perl servers, to guide you
through the tuning process. I have to admit, performance tuning is a
very hard task, and demands a lot of understanding and experience.
But once you acquire this knowledge you can make magic with your
server.

While developing your mod_perl applications, you will begin to
understand that an C<error_log> file is your best friend. It tells you
all the intimate details of what is happening to your scripts.  But
the problem is that it speaks a secret language. To learn the alphabet
and the grammar of this language, refer to the chapter L<Warnings and
Errors: Where and Why|troubleshooting/>.

L<Protecting Your Site|security/> - All about security.

If you are into driving relational databases with your cgi scripts,
the L<mod_perl and Relational Databases|databases/> chapter will tell
you all about the database-related goodies mod_perl has prepared for
you.

If you are using good old dbm files for your databases, the L<mod_perl
and dbm files|dbm/> chapter explains how to utilize them better under
mod_perl.

More and more Internet Service Providers (ISPs) are evaluating the
possibility of providing mod_perl services to their users. Is this
possible? Is it secure? Will it work?  What resources does it take?
The L<mod_perl for ISPs. mod_perl and Virtual Hosts|multiuser/>
chapter answers all these questions. If you want to run a mod_perl-
enabled server, but do not have root access, read this chapter as
well, either to learn how to do it yourself, or maybe to persuade your
ISP to provide this service.

If you have to administer your Apache mod_perl server the
L<Controlling and Monitoring the Server|control/> chapter is for
you. Among the topics are: server restarting and monitoring
techniques, preventing the server from eating up all your disk space
in a matter of minutes, and more.

(META: fix this)
The L<mod_perl Status. Peeking into the Server's Perl Innards|config/>
chapter shows you the ways you can peek at what is going on in a
mod_perl-enabled server while it is running. Like looking at the value
of some global variable, what database connections are open, looking
up what modules are loaded and their paths, what is the value of
C<@INC>, and much more.

Every programmer needs to know how to debug her program. It is an
_easy_ task with plain Perl. Just invoke the program with the C<-d>
flag and debug it. Is it possible to do the same under mod_perl? After
all you cannot debug every CGI script by executing it from the command
line: some scripts will not run from the command line. The L<Debugging
mod_perl|debug/> chapter proves debugging under mod_perl is possible.

Sometimes browsers that interact with our servers have bugs, which
cause big headaches for CGI developers. Coping with these bugs 
is discussed in the L<Workarounds for some known bugs in
browsers|browserbugs/> chapter.

Many modules were written to extend mod_perl's core
functionality. Some important modules are covered in the L<Apache::*
modules|modules/> chapter.

Some folks decide to go with mod_perl even though they are not
experienced Perl programmers. mod_perl is a demanding environment
which does not permit the `casual' programming style which plain Perl
allows.  Lack of knowledge/experience with Perl need not be any
barrier; Perl comes with copious and high quality on-line
documentation and there are many Perl books available which will get
you up to speed. Get a good Perl book and start reading. The L<Perl
Reference|perl/> chapter gives some basic, mod_perl specific Perl
lessons, delivering the knowledge without which you cannot start to
program mod_perl scripts.

The L<Code Snippets|snippets/> chapter is just a collection of code
snippets I have found useful while writing the scripts.

The L<Choosing an Operating System and Hardware|hardware/> chapter
gives you an idea on how to choose the software and hardware for the
webserver.

The L<mod_perl Advocacy|advocacy/> tries to make it easier to
advocate mod_perl around the world.

The L<Getting Help and Further Learning|help/> chapter refers you to
other related information resources, like learning Perl programming
and SQL, understanding security, building databases, and more.

L<Appendix A: Downloading software and documentation|download/>
includes pointers to the software that was explained and/or mentioned
in this guide.

=cut





