This is the installation document for AppWrap. It consists of these sections:
AppWrap consists of a MySQL database and Perl Modules running in the process space of a mod_perl enabled Apache web server. Thus, it has, so far, proven to be operating system independent. Let us know if you are having difficulty on your platform.
Appwrap is a make-based installation so can be installed like most packages. Brief steps follow. This procedure aims to get AppWrap running as quickly as possible. Once running it may be useful for you to refine your actual installation. See Customizing your install
If the prerequisites are already present there are 3 steps to get AppWrap running.
tar -zxvf appwrap-x.yy.tar.gz
Change to created directory.
cd appwrap-x.yy
Create the Makefile.
perl Makefile.PL
Build and install AppWrap.
make && make install
/path/to/mysqladmin CREATE AppWrap
# load the demo database
/path/to/mysql AppWrap < /path/to/appwrap/demo_db.txt
# create the AppWrap user. Note this is inserts into a different databse (mysql).
/path/to/mysql mysql < /path/to/appwrap/create_dbuser.txt
Your installation of MySQL may require user names and passwords. (This is better security.) If so, use the following command format to create the AppWrap database and user. <user> must be a MySQL user with select, insert and add privileges. <password> is the password for this privileged MySQL user.
/path/to/mysql -u <user> -p mysql < /path/to/AppWrap/create_dbuser.txt
/path/to/httpd -D Unix|Win32 -f /path/to/appwrap/conf/AppWrap.conf
That's it. Now enter an AppWrap URL into your browser's location window. (E. G., http://localhost/reports) Congratulations! You now have a working AppWrap installation. Click on any link to experiment with AppWrap. This is the view of AppWrap that your users will have. To get a sense of how AppWrap can ease your burden as a Webmaster, see the dcocumentation for adding a data table, http://localhost/getpage?chpt=script
If you see any errors in your browser, check your server's error log for help tracking them down. If you run MySQL with a log you can check this log for troubleshooting hints, too. Please report back to the AppWrap on SourceForge (https://sourceforge.net/forum?group_id=57509) your installation experience. We would like to make this installation as smooth as possible.
This above steps will get AppWrap running as quickly as possible. Once running it may be useful to you to refine your actual installation. Here are various ways to customize your installation and also your running AppWrap.
One of the advantages the Apache server over other servers is it's configurability. This is a mixed blessing as it may increase the complexity of setting up applications. Running Apache using the -f option as above is quick way to get started, and there are several areas you may wish to change in the config file. For example, the modules loaded when the server is started (the config file provided assumes your server was built as a DSO. See the Apache installation for more information), the log file names and composition, etc.
If there is an instance Apache server already running on your computer you can still run AppWrap alongside it. You could choose another port for the AppWrap version of Apache to listen to. This requires that all AppWrap URL include the port number. This certainly works, although it may be a little ugly or inconvenient. (You'll need to include the port number in the value of $config{'homeurl'} in the AppWrap.pm configuration file.
Another way to run an AppWrap instance alongside an existing Apache instance is to set up the ``two server configuration'' described in the Mod_perl Guide (See Resources below.) Using mod_perl, mod_rewrite and mod_proxy allows you great flexibility. The mod_perl Guide is a great source of inspiration and tips. We intend to provide more documentation and sample files with the AppWrap distribution in the future.
The AppWrap application can be customized in several places. This is one of the strengths of AppWrap, it can be fiddled to fit in your environment.
You may wish to assign AppWrap it's own domain name in your network, such as ``appwrap.yourdomain.com''. This may require mucking about with DNS, or editing your local /etc/hosts (or \windows\hosts) file. You'll also need to assign the domain in $config{dns} in AppWrap.pm, and in the Apache config file.
AppWrap needs the following components to be installed and working. Not all listed versions have been tested. However no difficulty should be expected. Biggest warning is Perl 5005. It is way old. Perl 5.6.1 hosted most AppWrap development. We have not yet tested Perl 5.8. Let us know what you find.
If you don't already have these applications running see Installing Prerequisites.
This section is included to help get the quickest possible working version of AppWrap. After that, please take the time to familiariaze yourself with the installation details of each individual package. We provide a quick and dirty approach that certainly could be customized for your system.
You can get the tarballs or binary distributions from the sites listed in the Resources section.
No sample installation steps available.
No sample installation steps available.
We recommend installing Apache using the ``DSO'' method. This gives you lots of flexibility to set up the best Apache/mod_perl configuration. Not that difficult, and definitely worth your time.
Here is how we did it. This should get you up and running fast. However it is a good idea to dig into the documentation and figure out the best way for you and for your system.
./configure --prefix=APACHE_PREFIX --libexecdir=LIBEXECDIR --enable-module=most --enable-shared=max
``APACHE_PREFIX'' is the path to the tree of Apache executables [/usr/local/apache-x.x.x/].
``LIBEXECDIR'' is the path to 3rd-party libraries (like mod_perl, mod_php) [/usr/local/apache_libs/]. This allows packages such as mod_perl and mod_php to evolve and upgrade without recompiling Apache.
make && make test && make install
We recommend installing mod_perl as a DSO outside of the Apache source tree. This allows the Apache and mod_perl sources to be upgraded independently.
perl Makefile.PL USE_APXS=1 WITH_APXS=/path/to/bin/apxs EVERYTHING=1 PERL_MARK_WHERE=1
WITH_APXS is where apache's ``apxs'' program lives [/usr/local/apache-x.x.x/bin/apxs].
You then need to move or copy the created libperl.a file into LIBEXECDIR used for Apache.
We recommend installing PHP as a DSO outside of the Apache source tree.
./configure --with-mysgl=/path/to/mysql --with-apxs=/path/to/bin/apxs
``with-apxs'' is where apache's ``apxs'' program lives [/usr/local/apache-x.y/bin/apxs]
``with-mysql'' is where the MySQL program lives [/usr/local/mysql]
You then need to move or copy the created libphp4.a file into LIBEXECDIR used for Apache.
It may be necessary to edit the php.ini file for your system. See the PHP documentation to determine that. =head2 Install phpMyAdmin
Any graphical MySQL front end should work fine; this is really to give the administrator easy access to the AppWrap administrative tables.
Thanks to the great work of the phpMyAdmin developers, the installation of phpMyAdmin is a breeze. Simply unpack the tarball, move the resulting directory into the ``htdocs'' (or whatever is the DoocumentRoot directory) of your Apache server, edit the ``config.inc.php configuration file, and that's it.
Although the phpMyAdmin configuration file is a mastery of customization possibilities, typically we make very few changes when installing a new release. Definitely do use security, we like the 'http' method.
The mod_perl Guide http://perl.apache.org/docs/1.0/index.html is an excellent resource for installing, configuring, programming and using mod_perl. Many thanks to Stas Beckman and all the Guide's contributors.
http://phpmyadmin.sourceforge.net/
The mod_perl mailing list has been especially useful. If you are already working with mod_perl and don't use this list, have a look at the archives: http://www.mathforum.org/epigone/modperl/
Windows users can download a complete binary of Apache, Perl, mod_perl and mod_ssl maintained by Randy Kobes at ftp://theoryx5.uwinnipeg.ca/pub/other/. Many thanks to Randy for this huge contribution.
ActiveState also has Perl, mod_perl and other packages for Windows. http://www.activestate.com/.