update installation page

We emphasize the binary installation because that is usually the simplest
method to install mitmproxy on all major platforms.

1 files changed, 69 insertions, 60 deletions

diff --git a/docs/install.rst b/docs/install.rst
index 1fe09aca..70b52731 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -3,117 +3,125 @@
 Installation
 ============
 
-.. _install-ubuntu:
+Please follow the steps for your operating system.
 
-Installation On Ubuntu
-----------------------
+Once installation is complete, you can run :ref:`mitmproxy`, :ref:`mitmdump` or :ref:`mitmweb` from a terminal.
 
-Ubuntu comes with Python but we need to install pip, python-dev and several libraries.
-This was tested on a fully patched installation of Ubuntu 16.04.
+
+.. _install-macos:
+
+Installation on macOS
+---------------------
+
+You can use Homebrew to install everything:
 
 .. code:: bash
 
-   sudo apt-get install python3-pip python3-dev libffi-dev libssl-dev libtiff5-dev libjpeg8-dev zlib1g-dev libwebp-dev
-   sudo pip3 install mitmproxy  # or pip install --user mitmproxy
+    brew install mitmproxy
 
-On older Ubuntu versions, e.g., **12.04** and **14.04**, you may need to install a newer version of Python.
-mitmproxy requires Python 3.5 or higher. Please take a look at pyenv_.
-Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
+Or you can download the pre-built binary packages from `mitmproxy.org`_.
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
 
+.. _install-windows:
 
-.. _install-fedora:
+Installation on Windows
+-----------------------
 
-Installation On Fedora
-----------------------
+The recommended way to install mitmproxy on Windows is to use the installer provided at `mitmproxy.org`_. After installation, you'll find shortcuts for :ref:`mitmweb` (the web-based interface) and :ref:`mitmdump` in the start menu. Both executables are  added to your PATH and can be invoked from the command line.
 
-Fedora comes with Python but we need to install pip, python-dev and several libraries.
-This was tested on a fully patched installation of Fedora 24.
+.. note::
+    mitmproxy's console interface is not supported on Windows, but you can use mitmweb (the web-based interface) and mitmdump.
 
-.. code:: bash
+.. _install-linux:
 
-   sudo dnf install make gcc redhat-rpm-config python3-pip python3-devel libffi-devel openssl-devel libtiff-devel libjpeg-devel zlib-devel libwebp-devel openjpeg2-devel
-   sudo pip3 install mitmproxy  # or pip install --user mitmproxy
+Installation on Linux
+---------------------
 
-Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
+The recommended way to run mitmproxy on Linux is to use the pre-built binaries provided at `mitmproxy.org`_.
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
+Our pre-built binaries provide you with the latest version of mitmproxy, a self-contained Python 3.5 environment and a recent version of OpenSSL that supports HTTP/2. Of course, you can also install mitmproxy from source if you prefer that (see :ref:`install-advanced`).
 
+.. _install-advanced:
 
+Advanced Installation
+---------------------
 
-.. _install-arch:
+.. _install-docker:
 
-Installation On Arch Linux
---------------------------
+Docker Images
+^^^^^^^^^^^^^
 
-mitmproxy has been added into the [community] repository. Use pacman to install it:
+You can also use the official mitmproxy images from `DockerHub`_.
+That being said, our portable binaries are just as easy to install and even easier to use. 😊
 
->>> sudo pacman -S mitmproxy
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
 
+.. _install-arch:
 
-.. _install-macos:
+Installation on Arch Linux
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+mitmproxy has been added into the [community] repository. Use pacman to install it:
 
-Installation On macOS
-------------------------
+>>> sudo pacman -S mitmproxy
 
-You can use Homebrew to install everything:
-.. code:: bash
 
-    brew install mitmproxy
 
-Or you can download the pre-built binary packages from `mitmproxy.org`_.
+.. _install-source-ubuntu:
 
-Once installation is complete you can run :ref:`mitmproxy` or :ref:`mitmdump` from a terminal.
+Installation from Source on Ubuntu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Ubuntu comes with Python but we need to install pip3, python3-dev and several libraries.
+This was tested on a fully patched installation of Ubuntu 16.04.
 
+.. code:: bash
 
-.. _install-windows:
+   sudo apt-get install python3-pip python3-dev libffi-dev libssl-dev libtiff5-dev libjpeg8-dev zlib1g-dev libwebp-dev
+   sudo pip3 install mitmproxy  # or pip3 install --user mitmproxy
 
-Installation On Windows
------------------------
+On older Ubuntu versions, e.g., **12.04** and **14.04**, you may need to install a newer version of Python.
+mitmproxy requires Python 3.5 or higher. Please take a look at pyenv_.
+Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
 
-.. note::
-    Please note that mitmdump is the only component of mitmproxy that is supported on Windows at
-    the moment.
+.. _install-source-fedora:
 
-    **There is no interactive user interface on Windows.**
+Installation from Source on Fedora
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Fedora comes with Python but we need to install pip3, python3-dev and several libraries.
+This was tested on a fully patched installation of Fedora 24.
 
-First, install the latest version of Python 3.5 from the `Python website`_.
-If you already have an older version of Python 3.5 installed, make sure to install pip_
-(pip is included in Python by default). If pip aborts with an error, make sure you are using the current version of pip.
+.. code:: bash
 
-.. code:: powershell
+   sudo dnf install make gcc redhat-rpm-config python3-pip python3-devel libffi-devel openssl-devel libtiff-devel libjpeg-devel zlib-devel libwebp-devel openjpeg2-devel
+   sudo pip3 install mitmproxy  # or pip3 install --user mitmproxy
 
-    python -m pip install --upgrade pip
+Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``.
 
-Next, add Python and the Python Scripts directory to your **PATH** variable.
-You can do this easily by running the following in powershell:
+.. _install-source-windows:
 
-.. code:: powershell
+🐱💻 Installation from Source on Windows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+    mitmproxy's console interface is not supported on Windows, but you can use mitmweb (the web-based interface) and mitmdump.
 
-    [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27;C:\Python27\Scripts", "User")
+First, install the latest version of Python 3.5 or later from the `Python website`_. During installation, make sure to select `Add Python to PATH`. 
 
 Now, you can install mitmproxy by running
 
 .. code:: powershell
 
-    pip install mitmproxy
-
-Once the installation is complete, you can run :ref:`mitmdump` from a command prompt.
-
+    pip3 install mitmproxy
 
-.. _install-source:
+.. _install-dev-version:
 
-Installation From Source
-------------------------
+Latest Development Version
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If you would like to install mitmproxy directly from the master branch on GitHub or would like to
-get set up to contribute to the project, install the dependencies as you would for a regular
-mitmproxy installation. Then see the Hacking_ section of the README on GitHub.
+get set up to contribute to the project, install the dependencies as you would for a regular installation from source. Then see the Hacking_ section of the README on GitHub.
 You can check your system information by running: ``mitmproxy --sysinfo``
 
 
@@ -122,3 +130,4 @@ You can check your system information by running: ``mitmproxy --sysinfo``
 .. _`Python website`: https://www.python.org/downloads/windows/
 .. _pip: https://pip.pypa.io/en/latest/installing.html
 .. _pyenv: https://github.com/yyuu/pyenv
+.. _DockerHub: https://hub.docker.com/r/mitmproxy/mitmproxy/