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 provison 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.
Tested on: Ubuntu 16.04 and Debian Stretch
sudo apt-get install -y build-essential 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, 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
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 version 1.8.4 of Ansible. Using virtualenvwrapper:
sudo apt-get install virtualenvwrapper mkvirtualenv -p python2.7 securedrop pip install ansible==1.8.4
Mac OS X¶
Install the dependencies for the development environment:
There are several ways to install Ansible on a Mac. We recommend setting up a virtual environment to install Ansible since we are currently using Ansible 1.8.4:
pip install virtualenvwrapper mkvirtualenv -p python2.7 securedrop pip install ansible==1.8.4
If you install
virtualenvwrapper and get a
command not found error, make sure
source /usr/local/bin/virtualenvwrapper.sh is in your
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
SecureDrop uses a branching model based on git-flow. The
branch always points to the latest stable release. Use this branch if you are
interested in installing or auditing SecureDrop. Development for the upcoming
release of SecureDrop takes place on
develop, which is the default
branch. If you want to contribute, you should branch from and submit pull