Skip to content

Commit

Permalink
Removes VirtualBox references throughout docs
Browse files Browse the repository at this point in the history 
Supplements freedomofpress/securedrop#5922.
Edits the dev docs to remove explicit mentions of Virtualbox, preferring
Libvirt (or Qubes) for any of the VM docs. Mostly this affects the macOS
docs. For macOS, we're now more clearly directing folks to use the
container dev env.
  • Loading branch information
Conor Schaefer committed May 4, 2021
1 parent 4282aec commit 3f8ec6d
Show file tree
Hide file tree
Showing 4 changed files with 11 additions and 334 deletions.
50 changes: 6 additions & 44 deletions docs/development/setup_development.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,10 @@ Overview

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, VirtualBox, and
specific type of development task. We use Vagrant, Molecule, and
Docker and our Ansible playbooks can provision these environments on
either virtual machines or physical hardware.

.. note:: SecureDrop is written in Python 3 only.

Quick Start
-----------

Expand Down Expand Up @@ -188,7 +186,7 @@ Setting Up a Multi-Machine Environment
.. note:: You do not need this step if you only plan to work on the
web application or the documentation.

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


Expand All @@ -201,7 +199,7 @@ Ubuntu or Debian GNU/Linux
sudo apt-get update
sudo apt-get install -y build-essential libssl-dev libffi-dev python3-dev \
dpkg-dev git linux-headers-$(uname -r) virtualbox
dpkg-dev git linux-headers-$(uname -r)
We recommend using the most recent version of Vagrant available in your distro's
package repositories. For Debian Stable, that's ``2.2.3`` at the time
Expand All @@ -227,9 +225,6 @@ from the `Vagrant Downloads page`_ and then install it.
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.
Expand Down Expand Up @@ -259,41 +254,8 @@ development-related tooling. Using `virtualenvwrapper
macOS
~~~~~

Install the dependencies for the development environment:

#. Vagrant_
#. VirtualBox_
#. Ansible_
#. rsync >= 3.1.0

If you use homebrew-cask_ to manage macOS apps, you can install Vagrant and
VirtualBox that way. As for Ansible, we strongly recommend installing it
in a virtual environment using ``virtualenvwrapper`` and ``pip``, so as not to
install the older version we use system-wide. You should create your virtualenv
using the Python 3 install on your system. If you are using a
different version, the path to ``virtualenvwrapper.sh`` will differ. Running
``pip show virtualenvwrapper`` should help you find it.

.. code:: sh
sudo easy_install pip # if you don't already have pip
sudo -H pip install -U virtualenvwrapper --ignore-installed six
source /usr/local/bin/virtualenvwrapper.sh
mkvirtualenv -p python3 securedrop
.. 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.

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``.

.. _Vagrant: https://www.vagrantup.com/downloads
.. _VirtualBox: https://www.virtualbox.org/wiki/Downloads
.. _Ansible: https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html
.. _Homebrew: https://brew.sh/
.. _homebrew-cask: https://sourabhbajaj.com/mac-setup/Vagrant/README.html

Developers on macOS should use the Docker-based container environment.
We don't support running VMs on macOS.

Fork & Clone the Repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -325,6 +287,6 @@ Qubes

To configure a multi-machine evironment in Qubes, follow the Quick Start instructions above to
create a standalone VM named ``sd-dev``, then follow the Linux instructions above to install the
required packages, *omitting* Virtualbox.
required packages.

Then, complete the steps described in :doc:`qubes_staging`.
7 changes: 3 additions & 4 deletions docs/development/upgrade_testing.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,9 @@ You can use this scenario to test the upgrade process, using using either
locally-built .debs or packages from the FPF test repo at
https://apt-test.freedom.press/. Both options are described below.

.. note:: The upgrade scenario uses QEMU/KVM via Vagrant's libvirt provider, in
place of the default Virtualbox provider. If you haven't already done so,
you'll need to set up the libvirt provider before proceeding. For
more information, see :ref:`libvirt_provider`.
.. note:: The upgrade scenario uses QEMU/KVM via Vagrant's libvirt provider.
If you haven't already done so, you'll need to set up the libvirt provider
before proceeding. For more information, see :ref:`libvirt_provider`.

.. _upgrade_testing_local:

Expand Down
49 changes: 1 addition & 48 deletions docs/development/virtual_environments.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,6 @@ one.
.. note:: If you plan to alter the configuration of any of these machines, make sure to
review the :ref:`config_tests` documentation.

.. note:: If you see test failures due to ``Too many levels of symbolic links``
and you are using VirtualBox, try restarting VirtualBox.

.. _staging_vms:

Staging
Expand Down Expand Up @@ -57,48 +54,6 @@ To rebuild the local packages for the app code and update the staging VMs:
The Debian packages will be rebuilt from the current state of your
local git repository and then installed on the staging servers.

.. note:: If you are using macOS and you run into errors from Ansible
such as ``OSError: [Errno 24] Too many open files``, you may need to
increase the maximum number of open files. Some guides online suggest
a procedure to do this that involves booting to recovery mode
and turning off System Integrity Protection (``csrutil disable``).
However this is a critical security feature and should not be
disabled. Instead follow this procedure to increase the file limit.

Set ``/Library/LaunchDaemons/limit.maxfiles.plist`` to the following:

.. code:: sh
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>limit.maxfiles</string>
<key>ProgramArguments</key>
<array>
<string>launchctl</string>
<string>limit</string>
<string>maxfiles</string>
<string>65536</string>
<string>65536</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>ServiceIPC</key>
<false/>
</dict>
</plist>
The plist file should be owned by ``root:wheel``:

.. code:: sh
sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
This will increase the maximum open file limits system wide on macOS
(last tested on 10.11.6).

The web interfaces and SSH are available over Tor. A copy of the the Onion URLs
for *Source* and *Journalist Interfaces*, as well as SSH access, are written to the
Vagrant host's ``install_files/ansible-base`` directory.
Expand Down Expand Up @@ -173,8 +128,7 @@ playbook from running with Vagrant-specific info.
You can provision production VMs from an Admin Workstation (most realistic),
or from your host. If your host OS is Linux-based and you plan to use an Admin
Workstation, you will need to switch Vagrant's default virtualization provider
from ``virtualbox`` to ``libvirt``. The Admin Workstation VM configuration
under Linux uses QEMU/KVM, which cannot run simultaneously with Virtualbox.
to ``libvirt``.

Instructions for both installation methods follow.

Expand Down Expand Up @@ -370,4 +324,3 @@ SSH Access
By default, direct SSH access is not enabled in the prod environment. You will need to log
in over Tor after initial provisioning or set ``enable_ssh_over_tor`` to "false"
during ``./securedrop-admin tailsconfig``.

Loading

0 comments on commit 3f8ec6d

Please sign in to comment.