===============
Getting started
===============

Install Python and Django
-------------------------

Helmholtz is built on top of the Django web framework, which uses the Python
programming language and is compatible with many different relational databases,
such as MySQL, PostgreSQL or Oracle. You will therefore need to install Python
(if you're running Linux or Mac OS X you probably have it already) and then
install Django. Python comes with a built-in database server, SQLite, which is
ideal for development and testing, so you probably don't need to install anything
else initially.

Full details on installing both Python and Django are available in the Django
`Quick install guide`_. (The `Django documentation`_ is excellent).

Install pip or easy_install
---------------------------

Each Helmholtz component is distributed as a separate package in the Python
Package Index (`PyPI`_). The easiest way to install packages is using one of the
tools ``pip`` or ``easy_install``. To test if you already have these installed,
open a shell and type::

    $ pip
    $ easy_install
    
If you don't have either of these installed, the easiest way to proceed
depends on your operating system. If you're running Linux, these tools are
probably available in your package manager, e.g. if you're running a recent
version of Ubuntu::

    $ sudo apt-get install python-pip

Otherwise it is probably easier to install ``easy_install`` following the
instructions `here <http://pypi.python.org/pypi/setuptools>`_. (Once you've
got ``easy_install``, it is simple to install ``pip`` using::

    $ easy_install pip

if you should wish to).

Install Helmholtz
-----------------

::

    $ pip install helmholtz
    
or::

    $ easy_install helmholtz

Choose Helmholtz components
---------------------------

Helmholtz is highly modular, so that you can pick and choose the components you
need for your database, as well as easily adding your own customizations and
extensions. A full list of components is given in :doc:`components`.

.. need a figure showing dependencies

For example, if you just wanted a database of brain regions as defined in an
atlas, you would need the components :mod:`core`, :mod:`units`, :mod:`species`,
:mod:`annotation` and :mod:`neuralstructures`. For a database of electrophysiological
recordings, you would need :mod:`core`, :mod:`units`, :mod:`species`,
:mod:`annotation`, :mod:`neuralstructures`, :mod:`access_control`, :mod:`people`,
:mod:`storage`, :mod:`measurements`, :mod:`equipment`, :mod:`chemistry`,
:mod:`location`, :mod:`preparations`, :mod:`experiment`, :mod:`recording`,
:mod:`signals`, :mod:`stimulation`, and :mod:`electrophysiology`.

We will soon add here a diagram showing the available components and their
dependencies.

Set-up a Django project
-----------------------

.. NOTE it might be a good idea to create our own script that generates a more customized settings.py, etc.

To create your database, you need to create and configure a Django "project".
First, create a skeleton project::

    $ django-admin.py startproject MyNeuroscienceDatabase
    $ cd MyNeuroScienceDatabase
    $ ls
    __init__.py     manage.py       settings.py     urls.py
    
You can see that Django has created a number of files. Open ``settings.py`` in a
text editor. You can see that it contains a number of settings, mostly with
default values. The ones you need to modify are the following::

    ADMINS = (
        ('Joe Bloggs', 'joe.bloggs@example.edu'),
    )
    
::

    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.sqlite3',
            'NAME': 'myneurosciencedatabase.db',
        }
    }

SQLite is a good choice for getting started, as it needs minimal configuration.
If you plan for your database to be widely used, especially if it will be
exposed on the Web, you will probably want to replace this later by a more
powerful database server such as PostgreSQL, MySQL or Oracle.

::

    TEMPLATE_DIRS = (
        "/path/to/MyNeuroscienceDatabase/templates",
    )
    
(replace "``/path/to/``" with the actual path to wherever your project lives).

::

    INSTALLED_APPS = (
        'django.contrib.auth',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.sites',
        'django.contrib.messages',
        'django.contrib.admin',
        'tagging',
        'helmholtz.core',
        'helmholtz.access_control',
        'helmholtz.units',
        'helmholtz.species',
        'helmholtz.people',
        'helmholtz.storage',
        'helmholtz.measurements',
        'helmholtz.annotation',
        'helmholtz.neuralstructures',
        'helmholtz.equipment',
        'helmholtz.chemistry',
        'helmholtz.location',
        'helmholtz.preparations',
        'helmholtz.stimulation',
        'helmholtz.experiment',
        'helmholtz.recording',
        'helmholtz.signals',
        'helmholtz.electrophysiology',
    )

The ``INSTALLED_APPS`` setting should contain the name of all the components
you chose earlier.
    
Now let's check everything worked. In the shell, type::

    $ python manage.py validate

If everything is configured correctly, you should see "``0 errors found``". If
you get an error, first check you have listed ''all'' of the components you need
in ``INSTALLED_APPS``, then please feel free to :doc:`contact` us. 
    
The next step will actually create the SQLite database::

    $ python manage.py syncdb

As part of this you will be asked to create a "superuser". This is basically an
administrator account that will allow you to modify things through the web interface.
Again, if you get any errors, please contact us.

Building the web interface
--------------------------

We had hoped to be able to complete a generic, example web interface for this
release, that you could customize or use as a guide for building your own
website. Unfortunately we ran out of time. Please contact us if you would like
to be notified when this becomes available.

.. Trying out the web interface
.. ----------------------------
.. 
.. Django comes with a built-in webserver, which is very useful for development
.. and testing, or for a personal database you will only use on one computer. (If
.. you want the database to be accessible from multiple computers in the lab, or
.. on the public internet, you will need to set up a proper webserver: see :doc:`deployment`.)
.. 
.. To run it, go back to the shell and type::
.. 
..     $ python manage.py runserver &
..     
.. Then open up a new page in your web-browser and go to http://127.0.0.1:8000/
.. 
.. You should see a comforting page saying "It worked! Congratulations on your first Django-powered page".
.. This is encouraging. Now we need to wire up the web interface to the database.
.. 
.. Wiring up the Web interface
.. ---------------------------
.. 
.. Open ``urls.py`` in a text editor, and modify it to look something like this::
.. 
..     from django.conf.urls.defaults import *
.. 
..     urlpatterns = patterns('',
..         (r'^data/', include('helmholtz.urls')),
..         
..     )
.. 
.. Go back to the web browser, and refresh the "It worked!" page.
.. 
.. You should see...
.. 
.. 
.. Now log-in, using the username and password you created when running ``syncdb``.
.. Of course, there is not much to see, because there's no data in the database yet.
.. 
.. You can now proceed to :doc:`populate the database <populating>`, or, if you
.. prefer, you can load up some example data (don't worry, you can delete it later).
.. 
.. **instructions on downloading and installing example data**


.. _`Quick install guide`: http://docs.djangoproject.com/en/1.2/intro/install/
.. _`Django documentation`: http://docs.djangoproject.com/
.. _`PyPI`: http://pypi.python.org/pypi/