Getting Started

Note

SecureDrop maintains two branches of documentation, stable and latest, the former being the default used by our Read the Docs powered site. stable is built from our latest signed git tag, while latest is built from the head of the develop git branch. In almost all cases involving development work, you’ll want to make sure you have the latest version selected by clicking the appropriate link above, or by using the menu in the bottom left corner.

Prerequisites

SecureDrop is a multi-machine design. To make development and testing easy, we provide a set of virtual environments, each tailored for a specific type of development task. We use Vagrant and VirtualBox to conveniently develop with a set of virtual environments, and our Ansible playbooks can provision these environments on either virtual machines or physical hardware.

To get started, you will need to install Vagrant, VirtualBox, and Ansible on your development workstation.

Ubuntu/Debian

Note

Tested on: Ubuntu 16.04 and Debian Stretch

sudo apt-get install -y build-essential libssl-dev libffi-dev python-dev \
    dpkg-dev git linux-headers-$(uname -r) virtualbox

We recommend using the latest stable version of Vagrant, 1.8.5 at the time of this writing, which might be newer than what is in your distro’s package repositories. Older versions of Vagrant has been known to cause problems (GitHub #932, GitHub #1381). If apt-cache policy vagrant says your candidate version is not at least 1.8.5, you should download the current version from the Vagrant Downloads page and then install it.

# If your OS vagrant is recent enough
sudo apt-get install vagrant
# OR this, if you downloaded the deb package.
sudo dpkg -i vagrant.deb

Warning

We do not recommend installing vagrant-cachier. It destroys apt’s state unless the VMs are always shut down/rebooted with Vagrant, which conflicts with the tasks in the Ansible playbooks. The instructions in Vagrantfile that would enable vagrant-cachier are currently commented out.

VirtualBox should be at least version 5.x. See GitHub #1381 for documentation of incompatibility with the older VirtualBox 4.x release series.

Finally, install Ansible so it can be used with Vagrant to automatically provision VMs. We recommend installing Ansible from PyPi with pip to ensure you have the latest stable version.

sudo apt-get install python-pip

The version of Ansible recommended to provision SecureDrop VMs may not be the same as the version in your distro’s repos, or may at some point flux out of sync. For this reason, and also just as a good general development practice, we recommend using a Python virtual environment to install Ansible and other development-related tooling. Using virtualenvwrapper:

sudo apt-get install virtualenvwrapper
source /usr/share/virtualenvwrapper/virtualenvwrapper.sh
mkvirtualenv -p /usr/bin/python2 securedrop
pip install -r securedrop/requirements/develop-requirements.txt

Note

You’ll want to add the command to source virtualenvwrapper.sh to your ~/.bashrc (or whatever your default shell configuration file is) so that the command-line utilities virtualenvwrapper provides are automatically available in the future.

Mac OS X

Install the dependencies for the development environment:

  1. Vagrant
  2. VirtualBox
  3. Ansible
  4. rsync >= 3.1.0

Note

Note that the version of rsync installed by default on macOS is extremely out-of-date, as is Apple’s custom. We recommend using Homebrew to install a modern version (3.1.0 or greater): brew install rsync.

There are several ways to install Ansible on a Mac. We recommend installing it to a virtual environment using virtualenvwrapper and pip, so as not to install the older version we use system-wide. The following commands assume your default Python is the Python2 that ships with macOS. If you are using a different version, the path to virtualenvwrapper.sh will differ. Running pip show virtualenvwrapper should help you find it.

sudo easy_install pip # if you don't already have pip
pip install -U virtualenvwrapper
source /usr/local/bin/virtualenvwrapper.sh
mkvirtualenv -p python2 securedrop
pip install -r securedrop/requirements/develop-requirements.txt

Note

You’ll want to add the command to source virtualenvwrapper.sh to your ~/.bashrc (or whatever your default shell configuration file is) so that the command-line utilities virtualenvwrapper provides are automatically available in the future.

Clone the repository

Once you’ve installed the prerequisites for the development environment, use git to clone the SecureDrop repo.

git clone https://github.com/freedomofpress/securedrop.git