Each new project starts out with the same structure, and base apps installed. Instead of manually creating the project structure and requirements every time I use a default project on github as the starting point.
For this tutorial we’ll be setting up a zoo site, the project name will be zoo.
First create the virtualenv for the zoo project from the terminal type:
mkvirtualenv --no-site-packages zoo
This will create a new virtualenv called “zoo” a “zoo” folder in ~/projects and activate the zoo virtualenv and change into the ~/projects/zoo directory. The “–no-site-packages” flag sets it so that none of the globally installed python packages will be available, setting this flag now is very helpful when moving the project to production. In the future to work on the zoo project just type workon zoo and it will activate the virtualenv and put you in the ~/projects/zoo directory. When done working on the project run the deactivate to get out of the zoo virtualenv.
Next download the default django project from github:
workon zoo
git clone git://github.com/punteney/default_project.git
mv default_project zoo
rm -rf zoo/.git
add2virtualenv zoo/website zoo/apps
The first line starts the zoo virtualenv. The second line copies down the base project from github for use. The third line renames the project from “default_project” to “zoo”. The fourth line removes the .git info as this will be a new project and should not continue to update the ‘default_project’ on github. Finally the last line adds the zoo/website and zoo/apps directory to the python path for the virtualenv so that python modules within those directory can be called directly.
Each project starts with the same default file structure. Later sections will explain the contents of the folders in more detail.
website/ - This is the django project folder for the site. It holds the settings files, urls, media, and project templates.
config/ - Holds various config files for things like Apache, nginx, wsgi, memcache, etc.
requirements/ - This folder holds the requirements files for packages that should be installed by pip.
docs/ - This folder is empty initially but is there to hold the generated documents for the project.
There are three pip requirements files in the requirements folder that contain the needed packages to be installed.
To install the requirements issue the following commands:
workon zoo
pip install -r zoo/requirements/dev.txt
Now that the default project is installed we need to configure it. All the settings are contained within the “zoo/website/settings” directory. The settings files within that directory are:
__init__.py - This settings file looks for an environment variable called “DJANGO_ENVIRONMENT” that is used to determine what other settings file should be imported. If no “DJANGO_ENVIRONMENT” is specified it will import the dev settings. In general unless you need to add a new “environment” you shouldn’t need to change this file.
base.py - This is the primary settings file. The settings in this file apply to all environments of the project (dev, production, staging) and should hold all the common settings for the project. In general this file should be thought of as the “settings” file.
- Environment specific settings - Each of these settings files will be applied to the different types of servers. The first thing each of these files does is import the base.py settings so any setting defined in these settings files will override the settings within base.py. Common settings to override are the database, email, cache, and debug settings. In general the fewer settings you include in these files the better.
- dev.py - Settings specific to the dev environment.
- production.py - Settings specific to the production environment
- staging.py - Settings specific to the staging environment
local.py - This is for settings that are specific to the server or settings that shouldn’t be included in the repository. The most common settings for local.py are the database password and secret key, if the source code repository isn’t secure. local.py is the last settings file included so any settings in it will override any previously defined settings. If a local.py settings is needed it should be created in the “website/settings” folder. As this file isn’t kept in the source control system you want to minimize the number of settings kept within it.
Go through the base.py file updating the appropriate settings. The ones that commonly need to be changed are:
>>> from random import choice
>>> ''.join([choice('abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)') for i in range(50)])
No changes should be needed for the dev settings file to get started on the project.
In the dev.py settings file it specifies a “dev.db” SQLite database. This is placed in a “data” folder outside of the project so as to not be included in the repository. All that needs to be done is to create the data folder:
mkdir ~/projects/zoo/data
With the data directory created Django will automatically create the SQLite dev.db when “syncdb” is run.
From the command line run syncdb and create the superuser when it requests it:
workon zoo
cd zoo/website/
./manage.py syncdb
Go to github and login if you aren’t already logged in. From your github dashboard page click the “new repository” button. For the “Project Name” enter ‘tutorial_zoo_site’, the other fields you can leave blank and leave the access to this repository to be ‘Anyone’ and create the repository.
Note
By setting the repository to be viewable by anyone any information that is within the repository will be public, so do not use the actual secret key or database passwords that are used for anything other than this sample project locally. On actual projects the source code repository will either be private and secure or you can use the local.py settings file to keep the private information out of the repository.
The next page on github will give you next step directions, some of which have been done earlier. This is the subset of the steps that still need to be done:
workon zoo
cd zoo
git init
ga * .gitignore
gcm -m 'Initial commit with default project setup'
git remote add origin git@github.com:YOUR-GITHUB-USERNAME/tutorial_zoo_site.git
gps origin master
Make sure to replace the “YOUR-GITHUB-USERNAME” with your actual username for github, in my case the line becomes git remote add origin git@github.com:punteney/tutorial_zoo_site.git
To make pushing and pulling from github a little easier add the following to the bottom of the ~/projects/zoo/zoo/.git/config file:
[branch "master"]
remote = origin
merge = refs/heads/master
With this specified in the git config file the gps origin master command above becomes just gps as it now knows the default remote for the ‘master’ branch is ‘origin’ which was already defined in the config file.
At this point it’s a default working project that you can build out from.