1. Getting Started

1.1. Prerequisites

You must have git installed - this can be done with a package manager such as brew or apt. Alternatively, you can find installers on the Git website.

The project is setup to be easily deployed with Vagrant. Make sure to install Vagrant and VirtualBox.

Finally, you need to have a SSH key setup. This is used for setting up local SSH in development mode and automated deployment (cloning of repositories from GitHub) in production mode.

note:If you want to use an SSH key other than the default, ~/.ssh/id_rsa (with the public key of ~/.ssh/id_rsa.pub), you can specify the paths with the SSH_KEY and PUB_SSH_KEY (for the public key) environment variables.
note:For production deployment, your SSH key must also be configured to allow SSH access to GitHub. When deploying in production mode, do not set a passphrase on your SSH key - this will cause the repository cloning to fail.

1.2. Cloning the Repository

To obtain the repository, simply clone it with git:

$ git clone ssh://[email protected]/PrincetonUniversity/Quizzera.git

If you do not have an SSH key setup with GitHub - which you really should, as that setup is required for other parts of the project - you can clone over HTTPS:

$ git clone https://github.com/PrincetonUniversity/Quizzera

1.3. Starting the Virtual Machine

Once you have Vagrant installed, run

$ vagrant up
note:On the first run, $ vagrant up can take anywhere from a half hour to a few hours to run, depending on your computer and network. The long time is due to the downloads required; Vagrant will download the OS image (currently, debian/jessie64) and then download and install of the required software for our stack. Because there are many dependencies, this can take quite a while to occur. On subsequent runs of $ vagrant up or $ vagrant provision, however, the process duration will be significantly shorter (often a few minutes at most).

To start the development server. By default, it will serve to localhost:8000.


If starting Vagrant crashes, you can restart the provisioning process (which will fix most bugs) by running

$ vagrant provision

To view a browsable API, visit localhost:8000/api/v1/. Alternatively, to view the Django administration site, go to localhost:8000/django/.

1.3.1. Vagrant Reference

  • $ vagrant up - start the virtual machine (VM) and run provisioning (if started for first time)
  • $ vagrant provision - provision the VM
  • $ vagrant suspend - put the VM to sleep
  • $ vagrant halt - shut down the VM
  • $ vagrant reload - restart the virtual machine, without provisioning
  • $ vagrant destroy - destroy the VM (starting again will require a full provision)
  • $ vagrant status - current status of the virtual machine
  • $ vagrant ssh - ssh into the VM as the default Vagrant user

In the development environment, you can also SSH into the machine as any of the users setup (see config.yml) through port 2222:

$ ssh -p 2222 [email protected]
$ ssh -p 2222 [email protected]
$ ssh -p 2222 [email protected]

1.4. Environment Settings

The Vagrant VM can be built with a few different settings, controlled by environment variables (and the configuration file, config.yml).

At the time of writing, there are two separate environments which have different settings and will be built differently by Vagrant:

  • development (default)
  • production (default in configuration)

To control the environment being used, set the ENV environment variable. If not specified, development is assumed.

Alternatively, you can specify it before every command:

$ ENV=production vagrant up
$ ENV=production vagrant provision

Primary differences in the two environments can be seen in the config.yml configuration file. The chosen environment’s configuration is recursively merged with the default configuration - note that the production environment has no explicit configuration, as the default settings are oriented towards production use.


Switching the ENV variable after the virtual machine is already started will have unexpected results.

For example, this does not work as expected:

$ ENV=production vagrant up
$ ENV=development vagrant provision

The provisioning phase, which is run with $ vagrant up, installs libraries (specific to the environment) and runs setup that is not reversible. As such, to switch environments, tear down the virtual machine and start a new one with the desired environment:

$ vagrant destroy -f
$ ENV=development vagrant up

However, switching environments is rarely necessary and should be avoided. For all development, use the development environment

1.5. Configuration

Almost all of the configuration for Quizzera, including that used in Django and Vagrant/Ansible, is managed through one config.yml file, which is located in the project’s root directory.

Changing the configuration is not as easy as changing the values in the file, however. Specifically, the Vagrant/Ansible configuration is difficult to reverse, and so simply changing a configuration parameter may not have immediate effects.

Each configuration value in the file is marked as volatile, provisioned, or permanent.

A volatile value will immediately affect Django or the related processes. However, those processes will still need to be restarted.

On the other hand, a provisioned value will require the server to be re-provisioned with Vagrant and Ansible. Ideally, the server will be reloaded (with $ vagrant reload --provision) to ensure changes take place.

Finally, a permanent value requires the server to be torn down (with $ vagrant destroy -f) and then restarted ($ vagrant up).

The ENV environment variable, as mentioned above, is a mix of all three types - it is used in many different places and will immediately affect some configuration or have no effect at all. In practice, the ENV variable should not be changed while a VM is running.

1.6. Final Setup

The final steps involve setting yourself up as a superuser on the Django site and enrolling yourself into the default course.

First, SSH into the virtual machine using $ vagrant ssh. Next, type in django to get to the correct directory with the environment setup. Then, add yourself as a superuser:

$ python manage.py createsuperuser

Username (leave blank to use 'vagrant'): {NETID}

Replace {NETID} with your Princeton Net ID. This will allow you to login to the Django administration panel.

Head to the administration panel at localhost:8000/django/. It gives you a nice interface to view the objects in the database - you’ll want to enroll yourself into the test course to get started.

First, go to http://localhost:8000/django/api/enrollment/. Click on the “Add Enrollment” button, select the course (“COS 0 - Fall 2016”, which has all of the usable questions) and your NetID as a user, check the “Is Admin” box, and press “Save”.

Now, you can go to http://localhost:8000/courses/ and view all of the available courses. Click the course you just enrolled into and check out the questions inside!


You may need to wait for the questions to be generated. Alternatively, you should make sure to load them from a cache file, if you have one.

To do so, run $ python manage.py loaddata {CACHE_FILE} where CACHE_FILE is the path to the file.

1.7. Production Deployment

When deploying in production, there are a few additional steps to follow. These steps are required because certain secure files cannot be placed in the repository. If you are deploying to production, you will have been granted access to these files/resources.

First, upload the Quizzera and Quizgen deployment keys to the quizzera user. Because you cannot sftp into root, you must do so as the quizzera user.

(localhost) $ sftp [email protected]
sftp > put id_quizzera
sftp > put id_quizzera.pub
sftp > put id_quizgen
sftp > put id_quizgen.pub
sftp > exit

Then, move those keys into root’s SSH directory.

(localhost) $ ssh [email protected]
([email protected]) $ sudo -i
([email protected]) $ mv -t ~/.ssh ~quizzera/id_quizzera ~quizzera/id_quizzera.pub
([email protected]) $ mv -t ~/.ssh ~quizzera/id_quizgen ~quizzera/id_quizgen.pub
([email protected]) $ logout
([email protected]) $ logout

Next, upload the production configuration file.

(localhost) $ sftp [email protected]
sftp> cd /var/secure
sftp> put quizzera-production.yml
sftp> exit

If there is a database password set in the quizzera-production.yml file, change the database user’s password, where {password} is the set value in the production configuration file.

(localhost) $ ssh [email protected]
([email protected]) $ sudo -u postgres psql
postgres=# ALTER USER quizzera WITH PASSWORD '{password}';
postgres=# \q
([email protected]) $ logout