view release on metacpan or  search on metacpan

lib/App/installguide/hosted.pod  view on Meta::CPAN

The advice of this section is highly subject to preference. What is described
here is a reasonable way to manage the development process of promoting code
changes and database changes from development through test into production.

We use one development environment. An "environment" is a top-level directory
which houses an instance of the application completely independent from the
next instance of the application. (An alternate style for slightly bigger
projects and teams would be to have one development "sandbox" environment
per developer, but I'll skip that here.)
The development environment points to the development database.

All environments that are not development environments are numbered
releases (or release candidates) (i.e. "1.0.0").  A numbered release
candidate of a web application is referred to as a test environment.
It is pointed to the test database until
all tests are completed and the release candidate is approved.
Then the release candidate is pointed to the production database, and
additional tests are performed that are not destructive to the data.

When it passes these final tests, it ceases to be a test environment
any longer, and it becomes the latest production environment.
A symbolic link is changed in order to point the "production" web
application to the latest numbered version.

=head1 PREPARING YOUR SOFTWARE ENVIRONMENT DIRECTORIES

First we choose a base direction where all software environment
directories will live.

   export PREFIX_BASE=$HOME/app

[Note: If you were doing this on a server where you had access to space
outside the home directory, you might make this something like
"/usr/mycompany" instead.]

Next, we prepare the environments.
We will assume that we are preparing a "devel" environment,
a single numbered release candidate "1.0.0" environment, and a symbolic
link for production that points to the "1.0.0" environment.

   mkdir $PREFIX_BASE
   mkdir $PREFIX_BASE/devel
   mkdir $PREFIX_BASE/devel/etc
   mkdir $PREFIX_BASE/devel/etc/app
   mkdir $PREFIX_BASE/devel/bin
   mkdir $PREFIX_BASE/devel/lib
   mkdir $PREFIX_BASE/devel/src
   mkdir $PREFIX_BASE/devel/data
   mkdir $PREFIX_BASE/1.0.0
   mkdir $PREFIX_BASE/1.0.0/etc
   mkdir $PREFIX_BASE/1.0.0/etc/app
   mkdir $PREFIX_BASE/1.0.0/bin
   mkdir $PREFIX_BASE/1.0.0/lib
   mkdir $PREFIX_BASE/1.0.0/src
   mkdir $PREFIX_BASE/1.0.0/data
   ln -s $PREFIX_BASE/1.0.0 $PREFIX_BASE/prod

=head1 CONFIGURE YOUR LOGIN ENVIRONMENT

Investigate what the "lib" directories are on the system and decide which of those
directories needs to be in the LD_LIBRARY_PATH (search path for libraries).

   # ls -ld /lib /*/lib /*/*/lib /*/*/*/lib

Investigate what the "man" directories are on the system and decide which of those
directories needs to be in the MANPATH (search path for "man" pages).

   # ls -ld /man /*/man /*/*/man /*/*/*/man

Make sure we have something intelligent for the following variables in "~/.bash_profile".

   export PATH=$PATH:$HOME/bin

   export LD_LIBRARY_PATH=/lib:/usr/lib:/usr/local/lib
   export MANPATH=/man:/usr/man:/usr/share/man:/usr/local/man:/usr/local/share/man
   export PERL5LIB=$HOME/lib/perl5:$HOME/lib/perl5/site_perl

   . prefix $HOME/app/devel

   set -o vi

Note: The prefix script comes with the App::Options distribution. It has been
installed in $HOME/bin.  The "prefix" script is bash-compatible and ksh-compatible.
It enhances the PATH's that have been set as appropriate.

Note 2: "set -o vi" is a bash setting I like to make command-line editing like
the vi-style of ksh. Leave this out if you like the default emacs-style
command-line editing.

Then log out and log back in.  Test that each variable had its desired effect.

   # which prefix
   # man ls
   # man App::Options
   # perl -MApp::Options -e 'print $App::Options::VERSION, "\n";'

=head1 INSTALL THE SOFTWARE

   # perl -MCPAN -e shell
   cpan> install App::Context
   cpan> install App::Repository
   cpan> install App::Widget
   cpan> exit

If any distribution fails to build (or any of the distributions they depend on),
exit the CPAN shell immediately and try to build manually.

For instance, App::Context depends on Devel::StackTrace.  If that module fails
to install, then App::Context will fail.  Exit the CPAN shell and build it by
hand.

   cd ~/.cpan/build/Devel-StackTrace*
   perl Makefile.PL PREFIX=/home/username
   make
   make test
   make install

Or if the distribution uses Module::Build, you may do the following.

   perl Build.PL install_base=/home/username
   ./Build
   ./Build test
   ./Build install

Sometimes a distribution fails some of the tests.  If it does, the CPAN shell
will not install it.  When you build it manually (as shown above), you may
decide that it is an error in the test suite rather than an error in the
modules themselves.  In this case, you can continue with the "install" step.
Then reenter the CPAN shell and install the next module.

IMPORTANT: If anyone discovers problems with these instructions or the
distributions related to the App::Context framework, please report them to me:

   spadkins@gmail.com

[I want to make this framework dirt simple to set up and use. -- spa]

=head1 SETTING UP A MySQL DATABASE

This will vary depending on your web hosting provider (and presumes they support
the use of MySQL databases).  I went to a control panel and did all the setup.
(This is all just an example of how I did it so that I can refer to this in later
setup documentation.  You will probably do this differently.)

I created three databases: "devel", "test", and "prod".  The control panel
prepended my hosting username, so they ended up being called "username_devel",
"username_test", and "username_prod".

Then I created three users: "dbview", "dbuser", and "dbadmin".  Again, the control
panel prepended my hosting username, so they ended up being called
"username_dbview", "username_dbuser", and "username_dbadmin".  I gave them
appropriate passwords and recorded what they were for future reference.

Then I went through each combination of database and database-user to assign
permissions to each.  I assigned all permissions to "username_dbadmin",
"select/insert/update/delete" permissions to "username_dbuser" and only "select"
permissions to "username_dbview".

I was then able to use the web-based database administration tool, "phpMyAdmin".
However, I prefer to do things from the command line.

The next thing I did was put my MySQL login credentials into the $HOME/.my.cnf file.

   [client]
   user            = username_dbadmin
   password        = my_password_here
   host            = localhost

   [mysql]
   database        = username_devel

Then it is *very* important to set the permissions on this file.

   chmod 600 $HOME/.my.cnf

This will keep anyone from reading the contents of the file (which contains your 
database password). Then you should be able to log in directly with the mysql
command line client.  Some sample commands are shown, but it is assumed that
you will read the MySQL documentation and know what you are doing.

   # mysql
   Welcome to the MySQL monitor.  Commands end with ; or \g.
   Your MySQL connection id is 1742668 to server version: 4.1.20-standard-log

   Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

   mysql> \s                             # show connection status