Madrona install on OSX

Instructions for installing madrona on a OSX Lion / Mountain Lion machine

John McKibbin 8/8/2012

These instructions are essentially a mashup of the following instruction sites that I found useful plus a fair bit of trial and error:
http://ecotrust.github.com/madrona/docs/installation.html#system-requirements
http://ecotrust.github.com/madrona/docs/tutorial_create.html#overview-example-madrona-project
http://russbrooks.com/2010/11/25/install-postgresql-9-on-os-x
https://docs.djangoproject.com/en/dev/ref/contrib/gis/install/#homebrew

# First install Xcode Developer Tools from the app store if you haven't already (it's free). These are required to compile the system dependencies from source.

# Then make sure the command line tools are installed in the Xcode settings menu (The most recent Xcode doesn't include these by default).

# Run the following scripts in a Terminal window, firstly to install Homebrew- a unix package manager for osx- this makes installs, uninstalls, package version switching and upgrades much easier
/usr/bin/ruby -e "$(/usr/bin/curl -fsSL https://raw.github.com/mxcl/homebrew/master/Library/Contributions/install_homebrew.rb)"

# Now use homebrew to install the system dependencies by typing these commands in the terminal
brew install gdal # Installs the geospatial data abstraction library
brew install geos # Installs the geometry engine
brew install proj # Installs the cartographic projections library
brew install mapnik # Installs the mapping application library
brew install postgresql # Installs the object relational database management system
# Then make sure you follow the instructions provided by homebrew to create a launch agent to launch postgres at startup, if you lost the instructions just type 'brew info PACKAGE_NAME' in the terminal. The instructions provided by homebrew will be a series of commands resembling the following.
initdb /usr/local/var/postgres
cp /usr/local/Cellar/postgresql/9.1.4/homebrew.mxcl.postgresql.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist
pg_ctl -D /usr/local/var/postgres -l /usr/local/var/postgres/server.log start
# Note the standard homebrew install allocates your operating system username as the postgresql superuser so you should already have superuser privileges. 
# If you experience an error when running initdb etc you may need to adjust the shared memory settings. See http://www.postgresql.org/docs/current/static/kernel-resources.html#SYSVIPC

# Then install the geospatial extension for the database management system using the following. The first command is required to tell homebrew to first download an older version of postgis (1.5.3), as geodjango isn't yet entirely compatible with the current version 2+ (as of 8/8/2012)
git checkout cb3d49e Library/Formula/postgis.rb # Pull the old version from the repository
brew install postgis # Installs the geospatial extensions for postgresql
# Once geodjango is compatible with version 2+ users could possibly try http://postgresapp.com/ for something easier

# Install virtualenv- a tool for installing python packages in isolated environments so they don't mess with other versions
easy_install virtualenv
# Install virtualenvwrapper a wrapper for virtualenv that makes working with the command line much easier (e.g. the command 'workon VIRTUALENV_NAME')
easy_install virtualenvwrapper

# You then need to modify your bash profile to recognise the above packages
touch ~/.bash_profile # creates a user profile for bash (i.e. the mac terminal) if you don't already have one
open ~/.bash_profile # opens your profile in the default editor alternatively use 'nano .bash_profile' to edit in the command line
# Copy the following text to the bottom of this file on its own line 
. virtualenvwrapper.sh # Activates the virtualenvwrapper when you launch a terminal window
export PYTHONPATH=/usr/local/lib/python2.7/site-packages:$PYTHONPATH # this is required only if using the system version of python
export PATH=/usr/local/bin:$PATH # this is a workaround for OSX Lion / Mountain Lion systems to avoid using the built in version of psql (contained in /usr/bin/) and use the brew installed version (contained in /usr/local/bin/). Essentially there is a built client version with insufficient functionality to use but enough functionality to be a problem, so you need to get it to ignore this installation by prioritising the brew installed edition. 
# then save and close the file

# Create a new virtual environment for the madrona app to live in
cd ~/.virtualenvs
virtualenv --system-site-packages madrona
# Activate the virtual environment
cd madrona
source bin/activate
# For future reference typing 'deactivate' will deactivate the virtual environment
# If you want to activate/change virtual environments type 'workon VIRTUALENV_NAME' (requires virtualenvwrapper)

# Install the madrona package and all its dependencies within the virtualenv container
pip install pil # this seems to be missing in the requirements file, if you don't do this first you will trigger an exception on the following command
pip install madrona

# Check that madrona has been installed correctly
python -c "import madrona; print madrona.get_version()" 
# The version number should be displayed

# Set up the postgresql/postgis database by running the following commands in the terminal
POSTGIS_SQL_PATH=/usr/local/share/postgis # this path is for the homebrew version only other installations will require a different path here
createdb -E UTF8 template_postgis
createlang -d template_postgis plpgsql # Adding PLPGSQL language support.
# Allows non-superusers the ability to create from this template
psql -d YOUR_NAME -c "UPDATE pg_database SET datistemplate='true' WHERE datname='template_postgis';"
# Load the PostGIS SQL routines
psql -d template_postgis -f $POSTGIS_SQL_PATH/postgis.sql
psql -d template_postgis -f $POSTGIS_SQL_PATH/spatial_ref_sys.sql
# Allow users to alter spatial tables.
psql -d template_postgis -c "GRANT ALL ON geometry_columns TO PUBLIC;"
psql -d template_postgis -c "GRANT ALL ON geography_columns TO PUBLIC;"
psql -d template_postgis -c "GRANT ALL ON spatial_ref_sys TO PUBLIC;"
# create the project database
createdb -T template_postgis madrona_db # madrona_db can be substituted for any database name
# Note: the template commands above will be far simpler once django becomes compatible with the latest version of postgis (i.e. +) see http://postgis.refractions.net/documentation/manual-2.0/postgis_installation.html#create_new_db_extensions. The new way will be one line something like this: psql -d YOUR_DATABASE -c "CREATE EXTENSION postgis;"

# Migrate to your preferred directory for your customised madrona instance to live in
cd /PATH_FOR_YOUR_PROJECTS
# Create a new instance of the madrona project by customising the following command to your requirements
create-madrona-project.py --project "Demo madrona" --app demomadronaapp --domain "127.0.0.1:8000" --connection "dbname='madrona_db' user='YOUR_NAME'" --studyregion "SRID=4326;POLYGON ((-125.0 41.8, -125.0 46.4, -116.4 46.4, -116.4 41.8, -125.0 41.8))" --aoi "My Areas of Interest" --folder "Collection of Features" --kml "Global Marine|http://ebm.nceas.ucsb.edu/GlobalMarine/kml/marine_model.kml"

# Navigate to the newly created working directory
cd madronademo/madronademo/

# Create a superuser account for you to administrate your new instance of madrona
python manage.py createsuperuser --username=admin --email=email@address.com # replace with your preferred username and email address
# you'll then be asked to provide a password to log into the admin page

# Launch the server
python manage.py runserver

visit http://127.0.0.1:8000/ in a browser to explore
visit http://127.0.0.1:8000/admin to access the admin page and provide the username and password you specified above