${project} README
===============

Requirements
============

	During development you'll need the following packages:
		
		- compass, to change the source (*.scss) files and to compile those to css
		- git
		- pip & virtualenv
		- libevent (sudo apt-get install libevent-dev)
		- nginx (sudo apt-get install nginx)
	
	For deployment you can ignore compass.

Quick Start
===========

	$$ ./bootstrap/bootstrap.py
	$$ source virtualenv/bin/activate
	$$ ./dev/work
	
	open http://localhost:8080 in your browser

	To deploy:

	-- do an initial commit of ${project} with git
	-- adjust etc/nginx/production.conf (namely the port and root directory to the project)
	-- adjust settings/production.py (DATABASE)
	-- setup ssh key authentication on your deployment server
	-- create a mysql/postgresql Database for your project on the deployment server (if required)
	-- change the variables in fabfile/__init__.py: HOST, USER
	
	$$ fab bootstrap
	$$ fab deploy
	
	Don't forget to activate the virtualenv as all the important scripts are stored under virtualenv (fab, pip)
	and won't work without activation.

	Your site should be ready now. Enjoy!

File Structure:
===============

	/
	+---/apps ----------------------- project-specific applications
	+---/bootstrap ------------------ scripts and files to setup a dev environment
	|   +---bootstrap.py ------------ main bootstrapping script
	|   +---dependencies.txt -------- a list of python packages that this project depends on (pip)
	|   +---setup_pip_virtualenv.sh-- 
	|   +---setup_ubuntu_packages.sh-
	+---/compass -------------------- compass' root directory with *.scss files under src.
	|   +---/src
	|   |   +---ie.scss
	|   |   +---print.scss
	|   |   +---screen.scss
	|   +---config.rb
	+---/db ------------------------- db-specific folder. By default settings.development stores a sqlite db here
	+---/dev ------------------------ scripts to aid during development and running servers
	|   +---__init__.py
	|   +---killsupervisor.py ------- script to shutdown the running supervisor daemon started with runsupervisor.py
	|   +---runserver.py ------------ run django's development server
	|   +---runsupervisor.py -------- run a supervisord daemon which automatically starts wsgi servers (runwsgi.py)
	|   +---runwsgi.py -------------- run a gevent-based wsgi server customized for django
	|   +---syncdb.py --------------- wrapper to manage.py syncdb. with "--noinput" and loading of fixtures
	|   +---work.py ----------------- helper script to run compass in the background and supervisord in development mode
	+---/etc ------------------------- configuration files for various 3rd party services in production
	|   +---/nginx ------------------- nginx specific configuration files
	|   |   +---development.conf ----- root folder points to this project folder by default
	|   |   +---production.conf ------ deployment server-specific configuration. don't forget to change the root folder
	|   +---/supervisor -------------- supervisord-specific config files
	|   |   +---development.conf
	|   |   +---production.conf
	+---/fabfile --------------------- scripts and files for the deployment process
	|   +---__init__.py -------------- Fabric configuration file. set USER and HOST here. (REPO_DIR, SITE_DIR optional)
	+---/fixtures -------------------- fixtures
	|   +---/development
	|   +---/production
	+---/lib ------------------------- non-django-specific, python-general package to store 3rd party libraries (or your own)
	|   +---__init__.py
	|   +---async.py ----------------- processes that run in a microthread under gevent (eg changemonitor)
	|   +---cmd.py ------------------- various functions to launch command-line tools, used by the other scripts (dev)
	+---/media ----------------------- django's media folder
	|   +---/site
	|   |   +---/css
	|   |   |   +---ie.css
	|   |   |   +---print.css
	|   |   |   +---screen.css
	|   |   +---/img
	|   |   |   +---grid.png
	|   |   +---/js
	|   |   |   +---jquery-1.4.2.min.js
	+---/settings
	|   +---__init__.py
	|   +---common.py ----------------- common and shared settings
	|   +---development.py ------------ development specific settings
	|   +---production.py ------------- production specific settings
	+---/templates
	|   +---/site
	|   |   +---base.html ------------- base layout to extend
	|   |   +---index.html
	+---/tmp -------------------------- directory to store various runtime files (supervisord's pid, logs etc)
	+---.gitignore
	+---manage.py
	+---README ------------------------ this file
	+---urls.py

Initial setup:
==============

	First setup the development environment and install all dependencies with

		$$ ./bootstrap/bootstrap.py

	This assumes you already have virtualenv and pip installed on your system. If not, install those packages with:

		$$ ./bootstrap/setup_pip_virtualenv.py

	After bootstrapping you should have all the dependencies listed in bootstrap/dependencies.txt properlly installed under virtualenv.

Notes on running the helper scripts
===================================

	Most of the scripts accept a parameter to specifiy the environment (development/production). Calling these
	without a parameter will result in telling you which environments are available. For nginx these are located
	under etc/nginx and for django's settings under settings. You can add your own environments by adding them in
	those specific folders. For example, to add a staging environment for django you'll add settings/staging.py and
	set the staging-specific variables there.

		etc/nginx/enable.py development|production 
		|
		+---- create a symlink with either dev/prod to nginx's sites-enabled folder under the name: ${project}
		
		dev/runsupervisor.py development|production 
		|
		+--- run supervisord with the specific settings. This will implicitly start and monitor wsgi servers with the
			 same settings (specificed via runwsgi.py). The wsgi servers will run with the name as your project, so you 
			 can kill them directly with "pkill ${project}". Supervisord will pick this up and start another fresh process
			 running the wsgi server. Adding "--nodaemon" will run the supervisor in front, for debugging purposes.

		dev/runwsgi.py development|production 
		|
		+--------- you can directly start the wsgi server without the supervisor by calling this script. In development
				   mode, a changemonitor will also run, which will kill the wsgi server. This is designed to be combined
				   with runsupervisor.py so the killing of wsgi results in a restart.

	Which should you use? For development you'll be working with

		$$ ./dev/work
	
	which will start a supervisor in development mode, thus a wsgi server in development mode and changemonitor enabled. 
	The supervisor will run with --nodaemon enabled. In production you'll want to use

		$$ fab deploy
	
	which will run ./dev/runsupervisor.py production

Django's Development server:
============================

	There is an advantage of having the same servers running during development and production to minimize infrastructure related bugs.
	Having said that, you can still run django's development server with

		$$ ./dev/runserver.py development|production

gevent & nginx - based production server:
=========================================

	Under etc/nginx/nginx.conf you'll find an nginx configuration file customized for this project. Enable this site on nginx by running

		$$ sudo ./etc/nginx/enable.sh development

	Run the gevent-based WSGI Handler

		$$ ./dev/runwsgi.py development

	After an nginx restart you should see your site at http://localhost:9000 running on gevent/nginx. Change the nginx.conf file as needed.

Deploying ${project} with Fabric:
===============================

	Under fabfile you'll find a preconfigured fab (Fabric) file for your project, which supports the following commands on the deployment server

		bootstrap     - create a bare git repo, add this repo to your local git, create the site structure, bootstrap virtualenv,
						install dependencies and enable nginx's site pointing to this project
		deploy        - push your changes to the remote site, run supervisord if it's not already running and restart wsgi servers
	
	and various other secondary commands, which are called via bootstrap or deploy

		install_nginx
		install_pip_virtualenv
		install_libevent
		setup_repo
		setup_site
		remove_repo
		remove_site
		run_wsgi
		kill_wsgi
		run_supervisor
		kill_supervisor
	
	You will have to do these things before you can deploy:

		1) copy your ssh key to your deployment server
		2) change your host settings in deploy/fab.py
		3) change etx/nginx/production.conf to suit your needs
	
		$$ fab deploy

Happy Hacking!
