From 18f200907484333f737a94c80a40bfe1563781b5 Mon Sep 17 00:00:00 2001 From: Maximilian Hils Date: Tue, 20 Dec 2016 17:34:35 +0100 Subject: update installation page We emphasize the binary installation because that is usually the simplest method to install mitmproxy on all major platforms. --- docs/install.rst | 129 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 69 insertions(+), 60 deletions(-) (limited to 'docs') 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/ -- cgit v1.2.3