INSTALL

F-or non-development installs we *highly* recommend using our standard
installation packages. Details here:

  http://localwiki.org/install

These packages are much easier to keep updated.

--------------------------------------------------------------------------------

The following install instructions are geared for development setups or non-Ubuntu
installs.

1.  Prerequisites: solr + jetty, python imaging library, python lxml bindings,
python-setuptools, virtualenv, gdal, postgresql with postgis.  Here's how we
get these packages in Ubuntu 12.04 LTS:

    $ sudo apt-get update
    $ sudo apt-get install python-setuptools solr-jetty python-lxml python-imaging
    $ sudo apt-get install gdal-bin proj python-psycopg2 default-jre-headless
    $ sudo easy_install --upgrade virtualenv

For Ubuntu 11.10 or greater:

    $ sudo apt-get install postgresql-9.1-postgis

For Ubuntu 11.04 or less:

    $ sudo apt-get install postgresql-8.4-postgis

2.  Create a virtualenv. For more info, see http://pypi.python.org/pypi/virtualenv.
*Note*: We store some important site-specific data in the virtualenv, so don't
delete it without first backing up the share/localwiki directory inside it.

    $ virtualenv --system-site-packages env
    
    Activate the new environment. Run all of the following commands in this environment:

    $ source env/bin/activate

3.  Install the localwiki package and its dependencies:

	(env)$ python setup.py install

4.  Allow the search, diff services to start & back up existing config.  This will
differ between systems.  We use this setup_jetty.sh script on Ubuntu & OS X:

    (env)$ install_config/setup_jetty.sh

Take a look at the setup_jetty.sh script (it's short). You may need to
customize it for your particular OS.

5. Initialize the localwiki install:

	(env)$ localwiki-manage setup_all

You'll be asked to sudo in order to create the postgres database.

You are now done configuring and installing things! You can start the built-in
Django development server:
    
    (env)$ localwiki-manage runserver

Hooray!  You can visit the site at http://127.0.0.1:8000/

Note: For security/efficiency, the built-in server listens on 127.0.0.1 only.
      For real deployments you'll want to set up apache.
      See https://dev.localwiki.org for more instructions.

Note: You'll want to run source env/bin/activate every time you want to access
      the localwiki-manage command.


=== Development note ===

If you're hacking on the code, you'll probably want to run, inside the virtualenv:

    (env)$ python setup.py develop

Instead of 'install'.  This makes the code update without having to run
'setup.py install' every time!

You'll also probably want to set DEBUG to False in share/conf/localsettings.py

To build the docs you'll want to install the optional requirements:

    (env)$ pip install -r install_config/optional.txt

-------------------------------------------------------------------------------
We've really only tested things on Ubuntu Server Edition 10.04 LTS.  It should
be very possible to run this on any Unix-y system.  You'll need to:

  * Hunt down the correct prerequisites for Step 1.
  * Make sure that Step 5 is completed.  Take a peek at install_config/setup_jetty.sh
    to see what it's doing.  It's simple stuff, really, but the configuration files
    may be in a different spot on your system.

Help us document this stuff!  Add something to https://dev.localwiki.org or
the github wiki.

== Database Note ==
This setup assumes we're using PostgreSQL and its geographic companion,
PostGIS.  You should in theory be able to use any supported Django database.
If you'd like to do something more specialized, please see the general Django
install instructions here:

http://docs.djangoproject.com/en/dev/topics/install/

and the GeoDjango install instructions here:

http://docs.djangoproject.com/en/dev/ref/contrib/gis/install/
-------------------------------------------------------------------------------