NOTE: THIS PROJECT IS NOW UNMAINTAINED. PLEASE SEE https://github.com/django/django-box FOR THE UPDATED VERSION.
The djangocore-box is a virtual machine (VM) containing all the programs and libraries required for running the Django core test suite in multiple different environments. Every supported version of Python (2.4, 2.5, 2.6, 2.7 and 3.3) is pre-installed as well as every supported database backend (SQLite, Spatialite, MySQL, PostgreSQL and PostGIS — Oracle is coming soon), all the GeoDjango dependencies and a number of third-party components such as Memcached and Python libraries like Sphinx, the Python Imaging Library, Textile and Markdown.
This is particularly useful to anybody interested in contributing to Django core without having to go through the trouble of installing and configuring all the software required to run the tests in all these environments.
First of all, you need to install the latest versions of Vagrant and VirtualBox on your host machine.
SSH-Agent will allow you to share the ssh keys on your host machine with the VM. This will then allow you to authenticate to remote servers, like github for example, from inside the VM.
First, check if your keys are added to ssh-agent:
ssh-add -l
If you don't have any keys, or the key you want available to the VM is not listed, you can add your key by running the following:
ssh-add <path_to_key>
Example:
ssh-add ~/.ssh/id_rsa
Legend: (host) is for commands to run on the host machine, and (vm) is
for commands to run inside the VM.
Setup the initial directory layout:
(host) $ mkdir djangocore
(host) $ cd djangocore
(host) $ git clone [email protected]:django/django.git # or replace django/django.git by <your username>/django.git if you have your own fork
(host) $ git clone [email protected]:jphalip/djangocore-box.git
(host) $ mkdir sandbox
Then, either:
-
If you have not already downloaded the box file separately, then run the following commands to boot the machine.
(host) $ cd djangocore-box (host) $ vagrant upThis will automatically download the VM, which is about 1GB in size (be warned if you have a low bandwitdh Internet connection) and then boot it up. The download will only occur the first time you run
vagrant up. Every subsequent times, it will just boot the VM, which only takes about 30 seconds. -
Or, if you have already downloaded the box file separately (say, for example someone gave it to you via a flash drive), then run the following command in order to import the box into vagrant and boot up the VM:
(host) $ vagrant box add djangocore-box-1.1 path/to/your/local/copy/of/djangocore-box-1.1.box (host) $ cd djangocore-box (host) $ vagrant upvagrant box addwill copy the box file to~/.vagrant.d/boxes, so you may delete the file you've dowloaded if you'd like to save some space on your hard drive.
As the VM boots up, it will prompt you to enter your host machine's administrator password (the same that you use for logging into your host machine). This is required so that Vagrant can setup the NFS shared folders.
Once the VM is up and running, type the following command to SSH into the VM
(still from inside the djangocore-box/ folder):
(host) $ vagrant ssh
Once inside the VM, you can run the tests by typing any of the pre-defined
aliases: runtests{2.4,2.5,2.6,2.7,3.3}-{sqlite,mysql,postgresql,spatialite,postgis}.
For example:
(vm) $ runtests2.6-mysql
(vm) $ runtests2.7-spatialite gis
(vm) $ runtests2.5-postgresql auth forms
You probably don't need to build the VM from scratch, but if you really want
it, the steps are still pretty simple. First, rename the file Vagrantfile to
a temporary name (e.g. Vagrantfile-backup) and then rename the file
Vagrantfile-build to Vagrantfile. Then run vagrant up. The automatic
build process will take about an hour. Use that time to do other work, browse
the web or go out for a nice stroll in the park!
In some cases, you will want to expose test projects, or test code to your host
machine. The sandbox directory on the host is mapped to the /sandbox
directory on the vagrant managed VM.
Any projects or code you create in /sandbox will be available in the
djangocore/sandbox directory.
Inside the VM, the /django folder is shared with the host and points to the
git clone that was created in the steps above. The repository clone for the
djangocore-box itself is also in a shared folder at /djangocore-box. This way
you can edit Django's code using your favorite editor/IDE from your host
machine and run the tests from inside the VM.
The various versions of python are installed in the /opt folder. The
virtualenvs are named py{2.4,2.5,2.6,2.7,3.3} and are installed under
/home/vagrant/.virtualenvs/.
virtualenvwrapper is also installed so you may run, for example:
(vm) $ workon py3.3
You should be able to push commits to your fork of django on github directly from inside the VM, as the SSH and git configuration files inside the VM are automatically symlinked to the corresponding files on your host machine. You may push those commits from the host machine too.
The test settings are available in /djangocore-box/test_settings/test_*.py.
These files are available in every virtualenv via symlinks.
Firefox is pre-installed so that Django's selenium tests can be run in headless
mode in a virtual display (with the id :99). For example, you may run a
specific test like so:
(vm) $ runtests2.6-sqlite admin_inlines.tests.SeleniumFirefoxTests --selenium
The VM is based on a Ubuntu 12.04 LTS 64 bits distribution.
To build the documentation, simply activate one of the virtualenvs and run the Sphinx build command:
workon py2.7
cd /django/docs
make html
-
To exit the VM and return to your host machine, simple type:
(vm) $ exit -
To shutdown the VM, type:
(host) $ vagrant halt -
To suspend the VM (i.e. freeze the VM's state), type:
(host) $ vagrant suspend -
Once shutdown or suspended, a VM can be restarted with:
(host) $ vagrant up -
To destroy the VM, simply type:
(host) $ vagrant destroy -
To check if the VM is currently running, type:
(host) $ vagrant status -
To re-run the provisioning after the VM has been started (if you have built the VM from scratch):
(host) $ vagrant provision -
More information is available in the Vagrant documentation.
- Install the Oracle backend.
djangocore-box was authored by Julien Phalip and other contributors.