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/install.rst') 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 From 42e9448adef2eb9b14616f71472ecae9cd267a84 Mon Sep 17 00:00:00 2001 From: Thomas Kriechbaumer Date: Wed, 21 Dec 2016 22:27:51 +0100 Subject: reflow docs --- docs/install.rst | 60 ++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 21 deletions(-) (limited to 'docs/install.rst') diff --git a/docs/install.rst b/docs/install.rst index 70b52731..93b3c364 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -5,7 +5,8 @@ Installation Please follow the steps for your operating system. -Once installation is complete, you can run :ref:`mitmproxy`, :ref:`mitmdump` or :ref:`mitmweb` from a terminal. +Once installation is complete, you can run :ref:`mitmproxy`, :ref:`mitmdump` or +:ref:`mitmweb` from a terminal. .. _install-macos: @@ -27,19 +28,28 @@ Or you can download the pre-built binary packages from `mitmproxy.org`_. Installation on Windows ----------------------- -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. +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. .. note:: - mitmproxy's console interface is not supported on Windows, but you can use mitmweb (the web-based interface) and mitmdump. + mitmproxy's console interface is not supported on Windows, but you can use + mitmweb (the web-based interface) and mitmdump. .. _install-linux: Installation on Linux --------------------- -The recommended way to run mitmproxy on Linux is to use the pre-built binaries provided at `mitmproxy.org`_. +The recommended way to run mitmproxy on Linux is to use the pre-built binaries +provided at `mitmproxy.org`_. -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`). +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: @@ -51,9 +61,8 @@ Advanced Installation Docker Images ^^^^^^^^^^^^^ -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. 😊 - +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. 😊 .. _install-arch: @@ -66,31 +75,32 @@ mitmproxy has been added into the [community] repository. Use pacman to install >>> sudo pacman -S mitmproxy - .. _install-source-ubuntu: 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. +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 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 -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``. +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``. + .. _install-source-fedora: 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. +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. .. code:: bash @@ -99,15 +109,19 @@ This was tested on a fully patched installation of Fedora 24. Make sure to have an up-to-date version of pip by running ``pip3 install -U pip``. + + .. _install-source-windows: 🐱💻 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. + mitmproxy's console interface is not supported on Windows, but you can use + mitmweb (the web-based interface) and mitmdump. -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`. +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 @@ -115,14 +129,18 @@ Now, you can install mitmproxy by running pip3 install mitmproxy + + .. _install-dev-version: 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 installation from source. Then see the Hacking_ section of the README on GitHub. -You can check your system information by running: ``mitmproxy --sysinfo`` +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 installation from source. Then see the +Hacking_ section of the README on GitHub. You can check your system information +by running: ``mitmproxy --sysinfo`` .. _Hacking: https://github.com/mitmproxy/mitmproxy/blob/master/README.rst#hacking -- cgit v1.2.3