Here are two ways to hack on

  1. Easy setup using Vagrant
  2. Manual setup

Easy setup using Vagrant

First, install Vagrant (2.0+) and Ansible (2.0+) on your machine. You should then be able to provision the Vagrant box.

$ vagrant up

The box will be provisioned with a latest Python 3.6 version, a virtual environment with all the requirements installed, and a database ready to use.

Once this is done it’s time to create some data and start the development server for the first time:

# SSH into the Vagrant box.
$ vagrant ssh
# Go to the pythondotorg/ directory and activate the virtual environment.
$ cd ~/pythondotorg
$ . venv/bin/activate
# Create initial data for the most used applications (optional).
$ ./ create_initial_data
# Set a password for the superuser "cbiggles". This username and password
# can be used to login to the admin environment.
$ ./ changepassword cbiggles
# Run the server.
$ ./ runserver

Now use your favorite browser to go to http://localhost:8001/. The admin pages can be found at http://localhost:8001/admin/. You can use your superuser credentials to log in to Django admin.

You will only need to run the following five commands the next time you want to work on

$ vagrant up
$ vagrant ssh
$ cd ~/pythondotorg
$ . venv/bin/activate
$ ./ runserver

Manual setup

First, clone the repository:

$ git clone git://

Then create a virtual environment:

$ python3.6 -m venv venv

And then you’ll need to install dependencies. You don’t need to use pip3 inside a Python 3 virtual environment:

$ pip install -r dev-requirements.txt

pythondotorg will look for a PostgreSQL database named pythondotorg by default. Run the following command to create a new database:

$ createdb pythondotorg -E utf-8 -l en_US.UTF-8


If the above command fails to create a database and you see an error message similar to:

createdb: database creation failed: ERROR:  permission denied to create database

Use the following command to create a database with postgres user as the owner:

$ sudo -u postgres createdb pythondotorg -E utf-8 -l en_US.UTF-8

Note that this solution may not work if you’ve installed PostgreSQL via Homebrew.

If you get an error like this:

createdb: database creation failed: ERROR:  new collation (en_US.UTF-8) is incompatible with the collation of the template database (en_GB.UTF-8)

Then you will have to change the value of the -l option to what your database was set up with initially.

To change database configuration, you can add the following setting to pydotorg/settings/ (or you can use the DATABASE_URL environment variable):

    'default': dj_database_url.parse('postgres:///your_database_name'),

If you prefer to use a simpler setup for your database you can use SQLite. Set the DATABASE_URL environment variable for the current terminal session:

$ export DATABASE_URL="sqlite:///pythondotorg.db"


If you prefer to set this variable in a more permanent way add the above line in your .bashrc file. Then it will be set for all terminal sessions in your system.

Whichever database type you chose, now it’s time to run migrations:

$ ./ migrate

To compile and compress static media, you will need compass and yui-compressor:

$ gem install bundler
$ bundle install


To install yui-compressor, use your OS’s package manager or download it directly then add the executable to your PATH.

To create initial data for the most used applications, run:

$ ./ create_initial_data

See create_initial_data for the command options to specify while creating initial data.

Finally, start the development server:

$ ./ runserver

Optional: Install Elasticsearch

The search feature in uses Elasticsearch engine. If you want to test out this feature, you will need to install Elasticsearch.

Once you have it installed, update the URL value of HAYSTACK_CONNECTIONS settings in pydotorg/settings/ to your local ElasticSearch server.

Generating CSS files automatically

Due to performance issues of django-pipeline, we are using a dummy compiler pydotorg.compilers.DummySASSCompiler in development mode. To generate CSS files, use sass itself in a separate terminal window:

$ cd static
$ sass --compass --scss -I $(dirname $(dirname $(gem which susy))) --trace --watch sass/style.scss:sass/style.css

Running tests

To run the test suite:

$ ./ test

To generate coverage report:

$ coverage run test
$ coverage report

Generate an HTML report with coverage html if you like.

Useful commands

  • Create a super user (for a new DB):

    $ ./ createsuperuser
  • Want to save some data from your DB before nuking it, and then load it back in?:

    $ ./ dumpdata --format=json --indent=4 $APPNAME > fixtures/$APPNAME.json