Improve macOS contributor instructions (#4327)

* remove instructions about removed Vagrantfile

* rewrite docker instructions

* say where docker-compose can be run

* give better intro for macOS devs

* prompt people for permission to install OS packages

* reword awkward sentence

* Change WORKDIR to /opt/certbot/src

This change is OK because all paths used in Dockerfile-dev are absolute paths.

* remove 'cd src' instructions for Dockerfile-dev

* Improve docker-compose testing instructions

Dockerfile-dev

@@ -13,7 +13,7 @@ EXPOSE 443
 # authenticator and text mode only?)
 VOLUME /etc/letsencrypt /var/lib/letsencrypt
 
-WORKDIR /opt/certbot
+WORKDIR /opt/certbot/src
 
 # no need to mkdir anything:
 # https://docs.docker.com/reference/builder/#copy

docs/contributing.rst

@@ -14,15 +14,24 @@ Getting Started
 Running a local copy of the client
 ----------------------------------
 
-Running the client in developer mode from your local tree is a little
+Running the client in developer mode from your local tree is a little different
-different than running ``certbot-auto``.  To get set up, do these things
+than running Certbot as a user. To get set up, clone our git repository by
-once:
+running:
 
 .. code-block:: shell
 
    git clone https://github.com/certbot/certbot
+
+If you're on macOS, we recommend you skip the rest of this section and instead
+run Certbot in Docker. You can find instructions for how to do this :ref:`here
+<docker>`. If you're running on Linux, you can run the following commands to
+install dependencies and set up a virtual environment where you can run
+Certbot. You only need to do this once.
+
+.. code-block:: shell
+
    cd certbot
-   ./letsencrypt-auto-source/letsencrypt-auto --os-packages-only
+   ./certbot-auto --os-packages-only
    ./tools/venv.sh
 
 Then in each shell where you're working on the client, do:
@@ -343,56 +352,36 @@ This should generate documentation in the ``docs/_build/html``
 directory.
 
 
-Other methods for running the client
+.. _docker:
-====================================
 
-Vagrant
+Running the client with Docker
--------
+==============================
 
-If you are a Vagrant user, Certbot comes with a Vagrantfile that
+You can use Docker Compose to quickly set up an environment for running and
-automates setting up a development environment in an Ubuntu 14.04
+testing Certbot. This is especially useful for macOS users. To install Docker
-LTS VM. To set it up, simply run ``vagrant up``. The repository is
+Compose, follow the instructions at https://docs.docker.com/compose/install/.
-synced to ``/vagrant``, so you can get started with:
 
-.. code-block:: shell
+.. note:: Linux users can simply run ``pip install docker-compose`` to get
+  Docker Compose after installing Docker Engine and activating your shell as
+  described in the :ref:`Getting Started <getting_started>` section.
 
-  vagrant ssh
+Now you can develop on your host machine, but run Certbot and test your changes
-  cd /vagrant
+in Docker. When using ``docker-compose`` make sure you are inside your clone of
-  sudo ./venv/bin/certbot
+the Certbot repository. As an example, you can run the following command to
+check for linting errors::
 
-Support for other Linux distributions coming soon.
+  docker-compose run --rm --service-ports development bash -c 'tox -e lint'
 
-.. note::
+You can also leave a terminal open running a shell in the Docker container and
-   Unfortunately, Python distutils and, by extension, setup.py and
+modify Certbot code in another window. The Certbot repo on your host machine is
-   tox, use hard linking quite extensively. Hard linking is not
+mounted inside of the container so any changes you make immediately take
-   supported by the default sync filesystem in Vagrant. As a result,
+effect. To do this, run::
-   all actions with these commands are *significantly slower* in
-   Vagrant. One potential fix is to `use NFS`_ (`related issue`_).
 
-.. _use NFS: http://docs.vagrantup.com/v2/synced-folders/nfs.html
+  docker-compose run --rm --service-ports development bash
-.. _related issue: https://github.com/ClusterHQ/flocker/issues/516
 
+Now running the check for linting errors described above is as easy as::
 
-Docker
+  tox -e lint
-------
-
-OSX users will probably find it easiest to set up a Docker container for
-development. Certbot comes with a Dockerfile (``Dockerfile-dev``)
-for doing so. To use Docker on OSX, install and setup docker-machine using the
-instructions at https://docs.docker.com/installation/mac/.
-
-To build the development Docker image::
-
-  docker build -t certbot -f Dockerfile-dev .
-
-Now run tests inside the Docker image:
-
-.. code-block:: shell
-
-  docker run -it certbot bash
-  cd src
-  tox -e py27
-
 
 .. _prerequisites: