Introduction

Included are shell provisioning scripts and sample configuration files allowing the construction of a Vagrant guest machine designed to support either full Django projects or the development of single Django apps for packaging and distribution.

The scripts are also designed to be run independently of Vagrant in order to provision production environments that match those used in development. See Usage in Production.

While various aspects of the provisioned environment are configurable, some are not. Therefore, it may not be suitable for all projects. In particular, the locations of various important directories (such as the Vagrant synced folder) and the system users used for various tasks are fixed.

Be sure to check out the Features and Limitations and Restrictions documentation.

How to use

  1. Copy the provision/ directory into your project.
  2. Copy the included Vagrantfile or add provision/scripts/bootstrap.sh as a shell provisioner in your existing Vagrantfile, specifying the project name. The included Vagrantfile is pretty basic, but it can be used as a foundation. See Vagrantfile for details.
  3. Modify the example provision/env.sh file. See env.sh for details.
  4. Add/modify any further configuration files to provision/conf/. See Configuring the environment for details on what further customisation options are available.
  5. Add any project-specific provisioning steps to a provision/project.sh file. See Project-specific Provisioning for details.
  6. Add provision/env.sh (and any other necessary config files) to your .gitignore file, or equivalent. Environment-specific configurations should not be committed to source control.
  7. vagrant up

In production environments, a few additional steps are necessary. See Usage in Production for details.

Note

When running a Windows host and using VirtualBox shared folders, vagrant up must be run with Administrator privileges to allow the creation of symlinks in the synced folder. See Windows Hosts for details.

Re-provisioning

The provisioning scripts can be re-run on existing environments to update them with any changes.

  • Any newly-added provisioning steps will be run.
  • Dependency packages will be updated if the specified versions have changed (e.g. in requirements.txt or package.json).
  • Config files in provision/conf will be re-copied.
  • Existing software will NOT be updated (the scripts do not run apt-get upgrade). This step will need to be run manually if required. Note: This is particularly important when provisioning a new environment.
  • env.py will NOT be overwritten if it exists. This allows it to be modified as necessary (either changing existing settings or adding new ones) without those changes getting replaced. As such, if the file needs rewriting (e.g. provisioning has been updated to change what it writes to env.py), it should be deleted first.

Upgrading

When upgrading to a new version of vagrant-django, do not replace the entire provision/ directory - that will wipe out any customised configuration files, templates, etc. The provision/scripts/ subdirectory is not designed to be customised, so it can safely be replaced as a whole. Modifications/additions to files in other subdirectories will be specified in the release notes, and can be updated individually.