view release on metacpan or  search on metacpan

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

   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
   mysql> show databases;                # show what databases defined
   mysql> show processlist;              # show all connections to the database
   mysql> show tables;                   # show all tables in this database
   mysql> use username_test;             # change to another database
   mysql> show tables;                   # show all tables in this database
   mysql> use username_prod;             # change back to the first database
   mysql> show tables;                   # show all tables in this database
   mysql> create table foo (foo_id integer not null auto_increment primary key,
          foo_dt date, foo_name varchar(255), foo_num integer) engine=MyISAM;
   mysql> show tables;
   mysql> drop table foo;
   mysql> create table foo (foo_id integer not null auto_increment primary key,
          foo_dt date, foo_name varchar(255), foo_num integer) engine=InnoDB;
   mysql> describe foo;
   mysql> show table status like 'foo';
   mysql> show indexes from foo;
   mysql> insert into foo (foo_dt, foo_name, foo_num) values ('2006-10-08','yowee',7);
   mysql> insert into foo (foo_dt, foo_name, foo_num) values ('2006-09-28','yowza',2);
   mysql> select * from foo;
   mysql> update foo set foo_num = 5 where foo_name = 'yowza';
   mysql> select * from foo;
   mysql> delete from foo where foo_dt = '2006-10-08';
   mysql> select * from foo;
   mysql> exit

=head1 SET UP THE FRAMEWORK TO READ THE DATABASE

=head2 CREATE app.conf

There are two kinds of configuration files in an application
written for the App::Context framework: app.conf and app.pl.

The "app.conf" file is the low-level configuration file.
"app.conf" is sometimes called the "options file" because
it is read by App::Options.
It contains parameters which are specific to the deployment
rather than to the structure of the application. 
It can be thought of as a "deployment descriptor".

For our purposes, the only thing unique about our installation
is the database connection information.

   vi $PREFIX/etc/app/app.conf

      dbhost = localhost
      dbname = username_prod
      dbuser = username_dbuser
      dbpass = my_password_here

   chmod 600 $PREFIX/etc/app/app.conf

=head2 CREATE app.pl

The "app.pl" file is the Application Configuration file.
This is where you define (and assemble) Services (i.e. components)
in the App::Context framework.

When an application is developed, a file like "app.pl" is part of the source
code of that application.  This file is not usually modified at the time
it is deployed along with supporting code into production.

For our example, we configure the Repository named
"dbprod" as a service in the "App::Repository::MySQL" class.
Then we configure the "default" Repository as an alias for "dbprod".

   vi $PREFIX/etc/app/app.pl

      $conf = {
        Repository => {
          default => {
            alias => "dbprod",
          },
          dbprod => {
            class => "App::Repository::MySQL",
          },
        },
      };

=head2 TEST THE CONNECTION

With the App-Context distribution comes a generic utility, "app", that can
be used to exercise any configured service.

Try the following.

   app Repository default get_rows foo

"app" takes the following arguments.

   1. The service type (here, it is "Repository")
   2. The service name (here, it is "default")
   3. The method to invoke on the service
   4+ The arguments to the method

Then it prints out whatever is returned from the method.

   # app Repository default get_rows foo
   $data = [
     [
       '2',
       '2006-09-28',
       'yowza',
       '5'
     ]
   ];

All programs that are built using the framework (with App-Options, App-Context,
and App-Repository) (such as "app") get a number of built-in features for free. 
You can experiment with the following.