Installation

Table of Contents

  1. Technical Background
  2. How do I check out the code?
  3. Commit accounts
  4. Installation Requirements
  5. Why did I install all this stuff?
  6. RUN THE APPLICATION
  7. Project setup (optional)
  8. Run The Application

Technical Background

You don't need l33t command line skills to develop our code. Ultimately, use whatever tools make developing fun and comfortable at the moment in your career.

Nonetheless, since command line instructions are more straightforward than GUI instructions, the rest of these instructions are in terms of the command line.

Please see our tech help for some friendly help for getting started. We hope it gives enough background for friends and mentors (like us at dev-flock@… or lucy@…) and Google to provide further aid.

How do I check out the code?

SVN repository location:

http://www.thoughtandmemory.org/repo/huginmunin/trunk

Browse the repository on our trac site through the [browser Browse Source] menu button at the top of the page.

If you have never used version control or repositories before have a look at this short flash video introducing subversion (svn).

Check out code via the command line like this (replace /home/bear/huginmunin_src with your desired destination): 

svn co http://www.thoughtandmemory.org/repo/huginmunin/trunk/web/hm /home/bear/hm_src

You can download svn here. For MacOS X, use Martin Ott's zipped dmg (v1.5) instead. Use the latest version (currently 1.5).

Graphical svn clients:

Commit accounts

Everyone who commits to trunk needs an account. This helps with social interaction and communication; eg, who to talk with about a particular part of the code. If you want an account send us mail (dev-flock@…).

Installation Requirements

1. Django - 1.0 or tip of the trunk. 

svn co http://code.djangoproject.com/svn/django/trunk django_src

2. python 2.4 or higher - Python is correctly installed when you can open a command prompt, type "python" and have the python evaluator run. The evaluator should also tell you the python version you are running. Type "quit()" or ctrl-d to quit. Helpful python tutorial

  • MacOS X: Python is probably already installed and on your path. If you have the wrong version follow these steps.
  • Windows: After installing python, add the path-to-your-python-exe-file (eg, C:\Python24) to your PATH environment variable. You must open a new command prompt after doing this. To find the environment variable dialog box in Windows go to "Start" -> "My Computer" (or "Computer" in Vista) -> "Properties" -> "Advanced" tab -> "Environment Variables" button. Wikipedia's guide to environment variables.

3. Python modules: mysqldb - for mysql only; if you're using the default sqlite3 configuration you don't need mysqldb.

4. A database engine supported by Django, such as sqlite3, mysql or postgres. The simplest database to use is sqlite3. Sqlite3 is correctly installed when you can open a command prompt, type "sqlite3" and have the sqlite3 program run. Type ctrl-d to quit.

  • MacOS X: Sqlite3 is probably already installed and on your path.
  • Awesome MySql cheat sheet

5. (optional) firebug, a firefox plugin, that helps with debugging client-side scripts, profiling rendering and investigating CSS, DOM and HTTP posts and responses. There is also an Internet Explorer, Opera and Safari compatible version, firebug lite.

Why did I install all this stuff?

Most web applications are comprised of three parts: the client-side browser computations (javascript, flash) and rendering (html, css); the server-side computations (python in our case; languages similar in function include php and ruby); and the data storage (databases such as sqlite3, mysql and postgre).

The bottom database layer is crucial; luckily some database application comes with most operating system distributions (except Windows).

The top HTTP layer is important for seeing the end web app, though not strictly necessary if you're working on python guts. All operating system distributions come with some kind of browser, though, so you don't need to do any work there (though eventually it's good to run multiple browsers and VMs for checking browser/OS support).

Django, written in Python, encompasses the middle layer. It provides useful libraries and abstractions between the bottom database level and the top HTTP level. We've added our own python utilities and API, too. Even if you OS has python, you'll still need to download Django. That wasn't so painful, was it?

RUN THE APPLICATION

The application, btw, is not all of trunk, but just trunk/web/hm. These instructions assume you're working out of there.

Project setup (optional)

You don't need to mess with local settings.py configuration if you're using sqlite3 and are OK with a default configuration; nonetheless, you might find this interesting.

In order for django to manage the backend, it needs to know where things live. This configuration occurs in the global settings.py file that is located in the root of the project. You checked out this file with the project and do not need to modify it.

You do need to add local configuration information about which database you're using. This means creating a local settings.py file in a sub-directory of env. env contains personal directories, each one containing a settings.py file specific to someone's personal machine.

For example, env/sqlite3_default contains a settings.py file with a default sqlite3 configuration, while env/dan contains a settings file with Dan's mysql and middleware information.

How does Django know which local settings.py file to use? Each project's env directory should contain a text file called CURRENT, which contains a single line of text that is the name of the directory to use for local setttings. CURRENT is not check in since it is specific to each person's setup.

If no env/CURRENT file exists, env/CURRENT.default is used by default, which may or may not work depending on your setup.

To configure your local settings: 1. Create a directory in env with a unique name 2. Create a text file in env called CURRENT which contains only the name of the directory you created in step 1. 3. Create a settings.py file that specifies database and middleware specific information. eg, for mysql: 

DEBUG = True
DEBUG_SQL = True
TEMPLATE_DEBUG = DEBUG

DATABASE_ENGINE = 'mysql'
DATABASE_NAME = 'hm_dev'
DATABASE_USER = 'bilumi'             # Not used with sqlite3.
DATABASE_PASSWORD = 'plaintextpassword!!one!'         # Not used with sqlite3.
DATABASE_HOST = 'set this if your msqld.sock is not in the usual place'             # Set to empty string for localhost. Not used with sqlite3.
DATABASE_PORT = ''             # Set to empty string for default. Not used with sqlite3.

MIDDLEWARE_CLASSES += (
    'lib.sql_log_middleware.SQLLogMiddleware',
    'lib.visit_log_middleware.LogVisits',
)

Run The Application

From the project root (same level as the global settings.py file):

0. Optional: Setup a database with test data

Create the tables with Django's manage.py. 

./manage.py syncdb

Load data from a fixture 

./manage.py loaddata db/fixtures/after_evolution/ready_to_upload.json

@TODO say more about loading data: actions, user weight corrections

In the future, use Django's manage.py script to dump and reload data. 

./manage.py help

1. Run the django dev server 

./manage.py runserver

2. Use the web app

Open a web browser and enter http://localhost:8000/Main (or the host and port number entered with runserver).