To use Luminotes, please see the included README file instead of this INSTALL
file. This file contains details about installing the Luminotes server, which
you shouldn't need if you only want to make a wiki.

First, install the prerequisites:

 * Python 2.5
 * CherryPy 2.2
 * PostgreSQL 8.1
 * psycopg 2.0
 * simplejson 1.3

In Debian GNU/Linux, you can issue the following command to install these
packages:

  apt-get install python2.5 python-cherrypy postgresql-8.1 python-psycopg2 python-simplejson

If you're using Debian Etch, see the note below about "psycopg in Debian
Etch".


development mode
----------------

Running the Luminotes server in development mode is convenient for testing out
changes, because it uses CherryPy's built-in web server with auto-reload
enabled, so the server will automatically reload any modified source files as
soon as they're modified.

Configure PostgreSQL's pg_hba.conf to require passwords for local connections:

  local all all md5

Restart postgresql so these changes take effect:

  /etc/init.d/postgresql restart

As the PostgreSQL superuser (usually "postgres"), create a new database user
and set the password to "dev".

  createuser -S -d -R -P -E luminotes

Initialize the database with the starting schema and basic data:

  psql -U luminotes postgres -f model/schema.sql
  psql -U luminotes postgres -f model/data.sql

To start the server in development mode, run:

  python2.5 luminotes.py -d

Connect to the following URL in a web browser running on the same machine:

  http://localhost:8081/


production mode
---------------

Production mode is intended for a live production web site, so you can skip
this section entirely if you don't care about running such a site. Production
mode doesn't support auto-reload, and logging goes to file (luminotes.log)
instead of the console, but performance should be better than in development
mode.

First you'll need to configure your web server to forward requests for
non-static pages to CherryPy. These instructions are for Apache, but in
theory, Luminotes should work with just about any web server.

In your Apache configuration file, enable mod_rewrite and mod_proxy, then add
the following rewrite rules to the settings for your VirtualHost:

  RewriteEngine on
  RewriteRule ^/favicon.ico /path/to/luminotes/static/images/favicon.ico [L]
  RewriteRule ^/static/(.*) /path/to/luminotes/static/$1 [L]
  RewriteRule ^(.*) http://127.0.0.1:8081$1 [P]

You should change the paths in the rules above to point to wherever Luminotes
happens to be installed. These rules cause Apache to serve static files
itself, while passing through requests for dynamic pages to the CherryPy web
server running locally.

Optionally, you can also enable Apache's mod_expires module and include the
following configuration along with the above rules:

  ExpiresActive On
  ExpiresDefault "A600"

This will tell clients not to request static pages more frequently than every
ten minutes (unless the user forces a reload).

If you want to use SSL, procure and install an SSL cert for use with Apache.
Add the above mod_rewrite rules to the settings for your SSL-enabled
VirtualHost, but change the IP in the last rule from 127.0.0.1 to 127.0.0.2.
This hack allows the Luminotes server to distinguish between SSL and non-SSL
requests by looking at the proxy IP. Without this, Luminotes would have no way
of knowing whether a particular request was encrypted when received by Apache.
(There are ways to do this in a less hacky manner with Apache 2, but not
Apache 1.)

To configure the Luminotes server for SSL support, edit config/Common.py and
change the values of luminotes.http_url and luminotes.https_url based on the
domain you're using. For instance:

  "luminotes.http_url": "http://luminotes.com",
  "luminotes.https_url": "https://luminotes.com",

Configure PostgreSQL's pg_hba.conf to require passwords for local connections:

  local all all md5

Restart postgresql so these changes take effect:

  /etc/init.d/postgresql restart

As the PostgreSQL superuser (usually "postgres"), create a new database user
and set the password to "dev".

  createuser -S -d -R -P -E luminotes

Initialize the database with the starting schema and basic data:

  psql -U luminotes postgres -f model/schema.sql
  psql -U luminotes postgres -f model/data.sql

Then to actually start the production mode server, run:

  python2.5 luminotes.py

You should be able to connect to the site at whatever domain you've configured
Apache to serve.


Python unit tests
-----------------

If you're interested in running unit tests of the server, install:

 * nose 0.9.0

In Debian GNU/Linux, you can issue the following command to install this
package:

  apt-get install python-nose

Then you can run unit tests by running:

  nosetests


JavaScript unit tests
---------------------

JsUnit is included with Luminotes, so to kick off tests of the client-side
JavaScript code, simply run:

  python2.5 static/js/test/run_tests.py

The run_tests.py script runs the tests inside browser windows and presumes you
have both Firefox and Internet Explorer 6 installed. Edit run_tests.py if you
need to specify different paths to the browser binaries or want to test with
additional browsers.


psycopg in Debian Etch
----------------------

As of this writing, Debian Etch does not contain a version of psycopg with
support for Python 2.5. However, the version of psycopg in Debian testing does
support Python 2.5. So you can grab the source for python-psycopg2 from Debian
testing, install the build dependencies (including python2.5-dev), and build
the package yourself on an Etch machine.

Then, edit /usr/share/python/debian_defaults and move "python2.5" from
"unsupported-versions" to "supported-versions". Finally, install the
python-psycopg2 package you've just built, and it should fully support Python
2.5.

See Debian bug #404355 for more information. Note that it was fixed in
unstable, but not in Etch.