
Installing ViewMTN
------------------

This document briefly describes what is necessary to install ViewMTN 
and configure a working installation. If something goes awry and you 
can't get ViewMTN to work, please feel free to contact me. See the 
contact details in "README"

Dependencies
------------

ViewMTN should run on any Unix based operating system - MacOS,
Linux, etc. It has not been ported to Windows, although that port
should be possible.

Monotone: http://monotone.ca/
A version which is descended from [62961c1dc..] is required.
This is post-0.30.

Python: http://www.python.org/
A version >= 2.4 is required.

Cheetah templates: http://www.cheetahtemplate.org/
Version 0.9.16-1 from Debian is known to work.

Flup: http://www.saddi.com/software/flup/dist/
Version: flup-r2311.tar.gz is know to work.

On a Debian machine, the following should give you what you need:
  apt-get install python-flup python-cheetah gnome-icon-theme highlight shared-mime-info
You might also want:
  apt-get install lighttpd
Unless you plan to run Apache, in which case:
  apt-get install libapache2-mod-fastcgi

Optional
--------

Highlight: http://www.andre-simon.de/
Version 2.4 is required for highlight work.
Highlight is required if source code is to be shown highlighted.

Shared Mime Info: http://freedesktop.org/wiki/Software/shared-mime-info
Version 0.19 is known to work, although there is a specification so older
versions should be fine. Most distributions provide this info.  Note that
if you install this into a non-standard path, please export XDG_DATA_DIRS
correctly (eg. XDG_DATA_DIRS=/opt/local/share) Without this package,
ViewMTN will only perform extremely basic MIME type auto-detection.

Icon Theme: http://www.freedesktop.org/software/icon-theme/
Any version should be fine. If possible, use a distributor version
of this package (Ubuntu is good!) as it will have a much richer
selection of icons. See later in this file to find out how to
configure ViewMTN to use icon themes.

Configuring ViewMTN
-------------------

ViewMTN can run in standalone mode, or under a web server. It is
recommended when first installing to ViewMTN to test it in standalone
mode.

If you have not already done so, copy "config.py.example" to
"config.py". You will then need to edit "config.py" to suit your 
site; there are numerous comments in the file, so this shouldn't be 
too hard.

You're then ready to run ViewMTN;
	./viewmtn.py <ip:port>

If you omit the <ip:port> argument, ViewMTN will bind to port 
127.0.0.1:8080.  You can access ViewMTN by visiting:
	http://localhost:8080/

If everything has gone well, you should get the normal ViewMTN front
page - a list of branches in the Monotone database you specified.
If not, look at the output of viewmtn.py on the console; perhaps it 
cannot read your monotone database, the path to 'mtn' is wrong, etc.

Running standalone in this mode is quite useful when using ViewMTN 
as an application for a single user. However, if you want to run a 
ViewMTN server for multiple users I suggest you have set up ViewMTN 
to run under a web server.

Running ViewMTN in a web server
-------------------------------

ViewMTN is based upon web.py (http://webpy.org/); the installation
instructions of webpy thus work for viewmtn. They are available 
here:
	http://webpy.infogami.com/install

In any of the examples, substitute "code.py" (or whatever) for 
web.py.

Lighttpd
--------

The following snippet of configuration is used to configure ViewMTN
on http://viewmtn.angrygoats.net/ (running lighttpd) and is therefore
known to work. You should be able to use it (with adjustment to
suit your site).

	fastcgi.server = ( "/viewmtn.py" =>
	(( "socket" => "/var/tmp/lighttpd/viewmtn.socket",
	   "bin-path" => "/home/grahame/mtn/viewmtn/viewmtn.py",
	   "max-procs" => 8,
	   "check-local" => "disable",
	))
	)

	## a static document-root, for virtual-hosting take look at the 
	## server.virtual-* options
	$HTTP["host"] == "viewmtn.angrygoats.net" {
		server.document-root       = "/home/grahame/mtn/viewmtn/"
		dir-listing.activate = "enable"

		url.rewrite-once = (
		       "^/favicon.ico$" => "/static/favicon.ico",
		       "^/static/(.*)$" => "/static/$1",
		       "^/(.*)$" => "/viewmtn.py/$1",
		)
	}

Apache2
-------

I've only tried ViewMTN under Apache with mod_fastcgi. Below is an 
example htaccess file for ViewMTN:
	# ExecCGI privilege is required to run the 
	# ViewMTN process
	Options +ExecCGI

	# Make sure you update config.py with this URL.
	<Files viewmtn.py>
	  SetHandler fastcgi-script
	</Files>

Copy this file to .htaccess in the viewmtn directory. This directory 
must have Options ExecCGI set. You might not be able to do this via 
directives in .htaccess, depending on site configuration; you may need 
to change the global server settings.

Unfortunately mod_fastcgi does not provide information in the environment 
so that web.py can automatically determine to run as fastcgi. Edit 
config.py, and set running_under_apache2 to True.
    running_under_apache2 = True

Note that if you ever want to run ViewMTN in a different mode, you 
will need reset this value to False.

After all of this you should be able to access ViewMTN at:
    http://hostname/path/to/viewmtn/viewmtn.py/

The trailing slash is important, otherwise you'll get a 404 error 
trying to access the page. Note that the URL for static content 
is:
    http://hostname/path/to/viewmtn/static/
 
Be sure to set both of these in config.py.

