{{{
#!text/x-rst
========================================
Preparing an Oracle GeoDjango test setup
========================================

Since GeoDjango requires full featured Oracle installation instead of XE this document
is meant to ease up installation and testing GeoDjango parts.

==============
Prerequisities
==============
On the host machine:
- Install Oracle client and set it up as documented in https://docs.djangoproject.com/en/1.4/ref/databases/#oracle-notes
- Install GeoDjango requirements as documented in https://docs.djangoproject.com/en/1.4/ref/contrib/gis/install/

On OS X, the general procedure to install cx_Oracle is:

* Download InstantClient from Oracle. You need the "Basic Lite" and "SDK" packages.
* Unzip them, merge them, and put the resulting directory in, for instance, `~/dev/oracle`.
* Set the following environment variables (you'll need them every time you use cx_Oracle)::

    export ORACLE_HOME=~/Documents/dev/oracle/instantclient_10_2
    export LD_LIBRARY_PATH=$ORACLE_HOME
    export DYLD_LIBRARY_PATH=$ORACLE_HOME

* Fix Oracle's package::

    ln -s libclntsh.dylib.10.1 $ORACLE_HOME/libclntsh.dylib 
    ln -s libocci.dylib.10.1 $ORACLE_HOME/libocci.dylib 

* Install cx_Oracle::

    pip install cx_Oracle

Adjust paths and versions as needed. There are plenty of more-or-less up-to-date tutorials on the web.


======================
How to get full Oracle 
======================

Easiest way is to use Oracle VirtualBox with prebuilt Oracle installation VM. We will be using the VM as a database server only.

#. Download and install **Oracle VirtualBox** from http://www.oracle.com/technetwork/server-storage/virtualbox/downloads/index.html or use package manager from your system.
#. Download **Oracle Developer Day** image from http://download.oracle.com/otn/other/virtualbox/dd/Oracle_Developer_Day.ova
#. Use VirtualBox to launch the image

 **NOTE: You may not use Oracle Developer Day VM for any other purposes than testing**

==============
Database setup
==============
On virtual machine:

#. Create a user and give the needed privileges::

    $ sudo su oracle
    $ sqlplus / as sysdba
    SQL> CREATE USER djangotest IDENTIFIED BY djangotest;
    SQL> GRANT DBA TO djangotest;
    SQL> quit
    $ exit

=========
Run tests
=========
On host:

#. Create geodjango_oracle.py settings file (change IP to one that is reported in VM console)::

    TEST_RUNNER = 'django.contrib.gis.tests.GeoDjangoTestSuiteRunner'

    DATABASES = {
    	'default' : {
    		'ENGINE' : 'django.contrib.gis.db.backends.oracle',
   		'PORT' : '1521',
    		'HOST' : 'VM IP',
    		'NAME' : 'orcl',
    		'USER' : 'djangotest',
    		'PASSWORD' : 'djangotest',
        },
    }
    SECRET_KEY = 'xxxxx'

#. Run tests::

    django-admin.py test --settings=geodjango_oracle
}}}