	##############################################
   ### MySource ------------------------------###
  ##- Installation Instructions --------------##
 #-- Copyright Squiz.net ---------------------#
##############################################

Herein are the instructions from installing and setting up MySource
on your system.

It is assumed your system satisfies all the MySource requirements.
If not, please ensure that it does before commencing installation.



===================
System Requirements
===================

MySource is currently only supported under Linux running the Apache
web server.

Hardware Requirements:

  We are still determining the hardware requirements of MySource. We
  doubt however these will exceed the requirements of a standard, but
  serious web server serving dynamic content.

Software Requirements:

  * GNU/Linux 2.0+
  * Apache 1.3
  * PHP 4.2.0
	* PNG Support (and required libraries)
	* GIF Support (and required libraries) (if your designs use them)
	* MySQL Support
  * MySQL 3.23


MySQL Requirements
------------------
-- http://www.mysql.com/downloads/
   Please Choose a mirror close to you.
-- It is downloadable either as an RPM or if you prefer, source code.
   Make sure you install the "devel" RPM if you choose to install
   with RPM's.

-- Version greater than 3.23.35.
   This is where it was developed, and has been extensively tested.
   Earlier versions are not guaranteed to work.


PHP Requirements
----------------
-- Downloadable only as source, http://www.php.net/downloads.php
   Choose a mirror close to you.
-- It is only downloadable as source code.

-- Version greater than 4.2.0
   This has some commands that previous versions of PHP didn't, so we
   need to make sure they are available for use.

   In summary, the minimum configure command for PHP has to have these
   options enabled:

   --with-gd
   --with-png-dir
   --with-zlib-dir
   --with-jpeg-dir
   --with-mysql

If you already have any other configuration options for PHP, add the
above options to them.

Recompile PHP, and test these options are available.

-- In the php.ini file, the "Short Tags" have to be enabled, with the
   line "short_open_tag = On"
   (This doesn't need compiling in, Apache just needs restarting to
   read in the INI file again).

Known Working PHP configure command
-----------------------------------
A php configure command known to work with MySource is as follows.

./configure \
--with-apxs=/usr/local/apache/bin/apxs \
--with-config-file-path=/etc \
--enable-versioning \
--enable-inline-optimization \
--enable-memory-limit \
--with-mysql=shared,/usr \
--with-gd=shared,/usr \
--enable-gd-native-ttf \
--with-ttf=/usr \
--with-xml \
--enable-wddx \
--with-zlib-dir=/usr \
--enable-mbstring \
--without-pear

Please note that this command does include options not specific to MySource and it is HIGHLY recommended that you install and review your php.ini file after installation of php.

This configure command relies on mod_so being built into Apache which allows you to load the php module without having to recompile apache. It has been successfully run on all Redhat Linux distributions between 6.2 and 7.2 inclusive using a compiled from source version of Apache 1.3.

To check if mod_so has been built into Apache run the command httpd -l and check to confirm that mod_so.c is in the output from running the command.



About Libraries Needed
----------------------

-- JPEG Libraries
   The JPEG libraries allow you to create / modify images "on the fly".
   MySource requires version 6b-10 or greater.

   They are available from:
   RedHat 6.2 - ftp://ftp.redhat.com/pub/redhat/redhat-6.2-en/os/i386/RedHat/RPMS/libjpeg-6b-10.i386.rpm
				ftp://ftp.redhat.com/pub/redhat/redhat-6.2-en/os/i386/RedHat/RPMS/libjpeg-devel-6b-10.i386.rpm
   RedHat 7.1 - ftp://ftp.redhat.com/pub/redhat/redhat-7.1-en/os/i386/RedHat/RPMS/libjpeg-6b-10.i386.rpm
				ftp://ftp.redhat.com/pub/redhat/redhat-7.1-en/os/i386/RedHat/RPMS/libjpeg-devel-6b-10.i386.rpm
   The RedHat 7.1 version is compatible with RedHat 7.0.

   If you prefer, the source code is available from
   ftp://ftp.uu.net/graphics/jpeg/

-- GD With GIF Library
   The GD libraries allow you to create / modify images "on the fly".
   This library also allows you to create / modify PNG images.
   The RPM is available from http://rpms.arvin.dk/gd-with_gif/ .
   A Source RPM is also available from this site. If you install from
   RPM's, remember to install the "devel" RPM, this is the one PHP
   needs.

   If you prefer, the source code is available from
   http://www.boutell.com/gd/

   Note : When you run the configure command for PHP, the default
   install location of the RPM is /usr/gd-with_gif, PHP doesn't look
   there by default so you have to tell it the path.
   Whatever location you use for --with-gd, you need to use the same
   location for --with-png when you configure PHP.

   Note: If your don't use GIFs in your site designs, you do not need
   GD With GIF.

-- ZLib
   The ZLib libraries allow compression of files, this is used by PNG
   so we need to add it into PHP.
   The source & RPM are available from http://www.gzip.org/zlib/

   Note: The RPM by default installs into /usr, so add this to the
   PHP configure command.


About Hit and Error Logging
---------------------------

The way MySource logs hit/visit statistics for pages has changed
between versions 2.2 and 2.4.

By default, MySource will not log any hits/visits to a page no matter
what settings are in the config. To turn logging on, a series of
environment variables are used. This change was implemented in
response to problems encountered when logging statistics for very
popular websites. A noticable slow-down occured for the sites, as
well as greatly increased database sizes. It was also decided that
the effects of logging statistics are, to a large degree, a server
admin issue which is why they are now controlled at a lower level.

To turn on visitor logging in MySource, the environment variable 
"MySource_LogVisitors" must be set to "on".
To log backend message, the environment variable 
"MySource_BackendLogMessages" must be set to "on".
To log web database queries, the environment variable 
"MySource_WebDatabaseLog" must be set to "on".
To log user database queries, the environment variable 
"MySource_UserDatabaseLog" must be set to "on".
To log banner impressions for the Banner Engine, the environment 
variable "MySource_BannerLogImpressions" must be set to "on".

When these environment variables are set to "on", the config settings in 
MySource will again be active. This means that the environment variable 
can be "on" but the MySource webmaster can still decide to turn off 
various logging options.

Another change that has been implemented is the sending of MySource 
errors via email. By default, error emails will be sent to the 
webmaster. However, the environment variable "MySource_ReportErrorEmail" 
can be set to redirect these emails to another email account. The value 
of this environment variable should be a valid email address.


============
Installation
============


Unzip and untar the MySource tarball (if you're reading this you've
probably already done that :):

$ gunzip -c mysource-x.x.tgz | tar xf -
$ cd mysource
$ ./configure

The configure script will prompt you for information as it:

	* Generates the inital configuration options (which can be altered
	  later)
	* Creates the MySQL database(s) and their tables.
	* Generates some example Apache configuration lines, which you
	  can paste into your httpd.conf file if you wish.

Any included MySource Xtras will be automatically installed during
this procedure as well.

The other alternative is to copy the "install.php" file into a web 
server accessable directory, and look at it through your browser.
Fill in the details, hit "Install", and you will be presented with
the details to copy into your httpd.conf file.

====================
Apache Configuration
====================

For now MySource is only supported running on the Apache web server.

There are two different ways to run the MySource web system - that is
whether or not to use "Virtual Paths". Virtual paths simulate a
directory structure on the web server, based on your MySource page
hierarchy. This way you can have URLs to your resources such as:

	http://mysource.squiz.net/downloads/mysource_0.9.1.tgz

Without Virtual Paths turned on (in the MySource configuration) you
need to instead use the URL:

	http://mysource.squiz.net/?f=63

This alternative is less friendly to site visitors - not to mention
search engine spiders and picky browsers!

Unfortunately to enable Virtual Paths you need access to Apache's
configuration file, which some MySource users will not have. This
is why turning Virtual Paths on is optional.

The key to running MySource using Virtual Paths are these five lines
in your Apache configuration:

	AliasMatch "^/(.*/)?__lib(.*)$" "MYSOURCE_PATH/web/__lib$2"
	AliasMatch "^/(.*/)?__squizlib(.*)$" "MYSOURCE_PATH/squizlib$2"
	AliasMatch "^/(.*/)?__data(.*)$" "MYSOURCE_PATH/data/unrestricted$2"
	AliasMatch "^/(.*/)?_edit(.*)$" "MYSOURCE_PATH/web/edit$2"
	AliasMatch "^/.*$" "MYSOURCE_PATH/web/index.php"

Where MYSOURCE_PATH is the path to the directory where you 
extracted MySource. The configure script should generate custom
lines for you (check for a file called Apache.conf after you run
configure).

The first line ensures that you can always access the MySource
backend by attaching "_edit" to any MySource URL. If you wish
to have a different suffix for your backend, simply change the
"_edit" in that line to "_admin" or "__BACKEND__" or whatever takes
your fancy. You do not need to include underscores (_'s) but it is
a nice way to distuguish between the backend and just another 
sub-page. For example, to edit the file mentioned above:

http://mysource.squiz.net/downloads/mysource_0.9.1.tgz/_edit

The first AliasMatch line overrides the second one which says
"every request made at this domain should be handled by the MySource
frontend controller". E.g.:

http://mysource.squiz.net/
http://mysource.squiz.net/downloads
http://mysource.squiz.net/a/really/long/path/that/actually/doesnt/go/anywhere

These will all be handled by MySource. If MySource can't find a
matching resource, it will redirect the user to the closest match.

If you only want to use MySource at a sub-directory of a domain, e.g.:

http://mysource.squiz.net/steve/mysource_test/

simply alter the lines as such:

	AliasMatch "^/steve/mysource_test(/.*)?/__lib(.*)$" "MYSOURCE_PATH/web/__lib$2"
	AliasMatch "^/steve/mysource_test(/.*)?/__squizlib(.*)$" "MYSOURCE_PATH/squizlib$2"
	AliasMatch "^/steve/mysource_test(/.*)?/__data(.*)$" "MYSOURCE_PATH/data/unrestricted$2"
	AliasMatch "^/steve/mysource_test(/.*)?/_edit(.*)$" "MYSOURCE_PATH/web/edit$2"
	AliasMatch "^/steve/mysource_test(/.*)?$" "MYSOURCE_PATH/web/index.php"

How ever you set up your Apache configuration, remember to configure
MySource itself accordingly. Under the "Config" tab in the MySource
backend, specify whether or not you are using Virtual Paths, and if
so, specify which suffix you are using (default is "_edit").

====================
Tomcat Configuration
====================

A recent feature added to MySource is a Java-based bulk file
uploader called 'jupload'. This system consists of a
browser-side Java applet and a server-side Java servlet. We
have successfully tested jupload on a system running Apache
and Tomcat. jupload can be found in the "squizlib/jupload"
directory. If you have tomcat running on your system you can
enable jupload by symlinking (or copying) this directory into
your Tomcat "webapps" directory. You can then specify the
appropriate URL to the directory in the MySource Configuration
screen. E.g. "http://beta.squiz.net/jupload/"



For more information visit our website.

Best of luck,

The MySource Team
http://mysource.squiz.net/
