Barcamp Bangkok Web App

Getting Started

Pre-requisites

Follow the setup instructions on the linked pages here for Windows. See the Linux/OS X sections below for recommended procedure if you're working on those platforms.

• Python (2.6.5+ and 2.7 are both fine)
• Python setuptools
• Python pip (after install setuptools, you should be able to do easy_install pip)
• Python virtualenv (after install pip, you should be able to do pip install virtualenv)
• Python Imaging Library (PIL)

We assume recent Ubuntu (Lucid) or OS X Snow Leopard here. Hopefully you can work things out on your own if you're not on these versions :-)

Mac OS X

Snow Leopard has Python 2.6.1 pre-installed. This will probably be fine. setuptools is also pre-installed, so you can jump right to:

$ sudo easy_install pip
$ sudo pip install virtualenv

Once you're working with virtualenvs you don't need to (and shouldn't) use sudo any longer for installing libraries with pip.

In order for PIL to build when installing the rest of the app's Python package dependencies below, you should install libjpeg. If you're using Homebrew, for instance:

$ brew install jpeg

Ubuntu Lucid

Just run sudo aptitude install python-virtualenv -- this will take take of installing Python, setuptools and pip for you as needed. You'll need to enable the Universe package repository if you haven't already.

In order for PIL to build when installing the rest of the app's Python package dependencies below, you should install a couple of prerequisite packages:

$ sudo aptitude install libjpeg-dev zlib1g-dev libfreetype6-dev

Both of the above

virtualenvwrapper makes life much nicer when working with virtualenvs:

$ sudo pip install virtualenvwrapper
$ mkdir ~/.virtualenvs

Edit your ~/.bashrc and add the following lines:

# virtualenvs & wrapper
export WORKON_HOME=$HOME/.virtualenvs
export PIP_VIRTUALENV_BASE=$WORKON_HOME
export PIP_RESPECT_VIRTUALENV=true
export VIRTUALENV_USE_DISTRIBUTE=true
source /usr/local/bin/virtualenvwrapper.sh

You should restart your shell for these to be set.

Working Environment

You will create an virtual Python environment, and activate it so that you will be working within it. This isolates packages you install from others on the system to avoid conflicts.

Windows

> virtualenv --no-site-packages barcamp_env
> barcamp_env\Scripts\activate.bat

This creates the environment in a directory, barcamp_env (you can name it whatever you like).

virtualenvwrapper (Linux/OS X)

$ mkvirtualenv --no-site-packages barcampbkk
$ workon barcampbkk

This hides the environment tidily away in the $WORKON_HOME we set.

Install App Dependencies

1. Install libraries required for the project:

   1. git clone [email protected]:barcampbangkok/barcampbkk.git
   2. Change into the barcampbkk directory and activate your virtualenv for the project.
   3. pip install -r requirements/development.txt
   4. See that all libraries are installed successfully (it should say so at the end), if not, you may want to open project.txt and install one-by-one for your machine).
   5. Create a file in settings/secrets.py for API keys and such -- you can get this from another developer.

2. Create the database for development. From inside the source code folder:

   fab startdev
   

   When it asks you to create an admin user, please create one. When it runs successfully, it will create dev.db in your source code folder and load some stub content from fixtures.

3. Symbolic link cms static files (Windows people, you will have to copy the folder over instead)

   ln -s <virtual environment site-packages folder>/cms/static/cms site_media/static/cms

4. Make sure tests are passing with your setup:

   fab test
   

5. Run the server:

   python manage.py runserver
   

6. Check if that works by going to http://localhost:8000/

7. Start hackin'

Note that the Barcamp app builds on django CMS, which uses the South project for database migration support, as any good modern Django project probably should. You're advised to browse the South tutorial if you're unfamiliar with it -- you should at least be prepared to run:

python manage.py schemamigration appname --auto
python manage.py migrate appname

after you make changes to models. You should also be conscious of running the migrate command when pulling in updates from SCM that contain migrations.

Internationalization & Localization

Django CMS allows entering content in multiple languages -- in the CMS Pages section of the administrative backend, you'll find that each created page has 'English' and 'Thai' tabs at the top.

For developers and tech-savvy translation volunteers, become familiar with Django's localization support to translate text strings within the application (not in the site CMS content). In summary, you generate updated messages strings to be translated using:

python manage.py makemessages -l th

if you're going to add/update Thai translations, for instance. Then edit locale/th/LC_MESSAGES/django.po to change the values (msgstr) for each identifier (msgid) found from the application code or templates containing the string you want to translate. When you've finished, run:

python manage.py compilemessages

and then commit the changed files into version control.

Note

You'll need to install GNU gettext in the preferred manner for your platform in order to use the messages manage.py commands.

Social Network Authentication

For development, you'll need to update site domain in the Sites table to the domain you're running at e.g. 127.0.0.1:8000 This will be sent to Twitter for callback.

For production, assuming we're going to deploy at barcampbangkok.org, just make sure that the site domain is barcampbangkok.org

HACKS

Dirty things to be aware that we should fix if there is a better solution in the future.

1. Monkey-patched loaddata management command to work around a signal bug in django-cms that causes fixture loading to fail. This is in the 'hacks' app.

Deployment

The short answer is:

fab production deploy

This will attempt to install anything added to the pip requirements during the deploy, and will run any added South migrations as well.

There are `some additonal details`_ about how deployment is handled that are important for you to know about -- please see the wiki page.

Infrastructure Management

Server configuration is automated by Chef. Documentation on how to work with it is available on the project's Chef repo wiki. You should not make changes on the server without supporting, tested Chef automation!