Rooba
/
mitmproxy
mirror of https://github.com/mitmproxy/mitmproxy.git
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

simplify install instructions

This commit is contained in:
Maximilian Hils 2019-11-20 18:40:43 +01:00
parent 3a7ca3e1e7
commit 6ad7b575bb
2 changed files with 54 additions and 75 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
README.rst
View File

@ -57,7 +57,16 @@ please consider contributing in the following areas:
Development Setup
-----------------
To get started hacking on mitmproxy, please follow the `advanced installation`_ steps to install mitmproxy from source, but stop right before running ``pip3 install mitmproxy``. Instead, do the following:
To get started hacking on mitmproxy, please install a recent version of Python (we require at least 3.6).
The following commands should work on your system:
.. code-block:: bash
python3 --version
python3 -m pip --help
python3 -m venv --help
If all of this run successfully, do the following:
.. code-block:: bash
@ -86,17 +95,12 @@ Testing
-------
If you've followed the procedure above, you already have all the development
requirements installed, and you can run the full test suite (including tests for code style and documentation) with tox_:
requirements installed, and you can run the full test suite with tox_:
.. code-block:: bash
tox
To run complete tests with a full coverage report, you can use the following command:
.. code-block:: bash
tox -- --verbose --cov-report=term
tox -e py # runs Python tests
tox -e lint # checks code style
For speedier testing, we recommend you run `pytest`_ directly on individual test files or folders:
@ -105,7 +109,7 @@ For speedier testing, we recommend you run `pytest`_ directly on individual test
cd test/mitmproxy/addons
pytest --cov mitmproxy.addons.anticache --cov-report term-missing --looponfail test_anticache.py
As pytest does not check the code style, you probably want to run ``tox -e lint`` before committing your changes.
Pytest does not check the code style, so you want to run ``tox -e lint`` again before committing.
Please ensure that all patches are accompanied by matching changes in the test
suite. The project tries to maintain 100% test coverage and enforces this strictly for some parts of the codebase.

105
docs/src/content/overview-installation.md
View File

@ -19,14 +19,12 @@ The recommended way to install mitmproxy on macOS is to use
brew install mitmproxy
{{< / highlight >}}
Alternatively you can download the binary-packages from our
[releases](https://github.com/mitmproxy/mitmproxy/releases/latest) page.
Alternatively, you can download standalone binaries on [mitmproxy.org](https://mitmproxy.org/).
## Linux
The recommended way to install mitmproxy on Linux is to download the
binary-packages from our
[releases](https://github.com/mitmproxy/mitmproxy/releases/latest) page.
standalone binaries on [mitmproxy.org](https://mitmproxy.org/).
Some Linux distributions provide community-supported mitmproxy packages through
their native package repositories (e.g., Arch Linux, Debian, Ubuntu, Kali Linux,
@ -37,15 +35,14 @@ the repository maintainers directly for issues with native packages.
## Windows
All the mitmproxy tools are fully supported under [WSL (Windows Subsystem for
Linux)](https://docs.microsoft.com/en-us/windows/wsl/about). We recommend to [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and then
All the mitmproxy tools are fully supported under
[WSL (Windows Subsystem for Linux)](https://docs.microsoft.com/en-us/windows/wsl/about).
We recommend to [install WSL](https://docs.microsoft.com/en-us/windows/wsl/install-win10), and then
follow the mitmproxy installation instructions for Linux.
We also distribute native Windows packages for all tools other than the
mitmproxy console app, which only works under WSL. To install mitmproxy on Windows,
download the binary packages from our
[releases](https://github.com/mitmproxy/mitmproxy/releases/latest) page.
download the installer from [mitmproxy.org](https://mitmproxy.org/).
After installation, you'll find shortcuts for mitmweb and mitmdump in the start
menu. Both executables are added to your PATH and can be invoked from the
command line.
@ -53,12 +50,40 @@ command line.
# Advanced Installation
## Self-contained Pre-built Binary Packages
## Development Setup
For some platforms we provide pre-built binary packages containing ready-to-run
executables. This includes a self-contained Python 3 environment, a recent
OpenSSL that support ALPN and HTTP/2, and other dependencies that would
otherwise be cumbersome to compile and install.
If you would like to install mitmproxy directly from source code or the
GitHub master branch, please see the our
[README](https://github.com/mitmproxy/mitmproxy#installation)
on GitHub.
## Installation from the Python Package Index (PyPI)
If your mitmproxy addons require the installation of additional Python packages,
you can install mitmproxy from [PyPI](https://pypi.org/project/mitmproxy/).
While there are plenty of options around[^1], we recommend the installation using pipx:
[^1]: If you are familiar with the Python ecosystem, you may know that there are a million ways to install Python
packages. Most of them (pip, virtualenv, pipenv, etc.) should just work, but we don't have the capacity to
provide support for it.
1. Install a recent version of Python (we require at least 3.6).
2. Install [pipx](https://pipxproject.github.io/pipx/).
3. `pipx install mitmproxy`
To install additional Python packages, run `pipx inject mitmproxy <your-package-name>`.
## Docker Images
You can use the official mitmproxy images from
[DockerHub](https://hub.docker.com/r/mitmproxy/mitmproxy/).
## Security Considerations for Binary Packages
Our pre-compiled binary packages and Docker images include a self-contained Python 3 environment, a recent version of
OpenSSL that support ALPN and HTTP/2, and other dependencies that would otherwise be cumbersome to compile and install.
Dependencies in the binary packages are frozen on release, and can't be updated
in situ. This means that we necessarily capture any bugs or security issues that
@ -67,54 +92,4 @@ dependencies (though we may do so if we become aware of a really serious issue).
If you use our binary packages, please make sure you update regularly to ensure
that everything remains current.
## Docker Images
You can use the official mitmproxy images from
[DockerHub](https://hub.docker.com/r/mitmproxy/mitmproxy/). The same
security considerations apply as for our binary packages.
## Installation on Linux via pip3
Please make sure to install Python 3.6 (or higher) and pip3 for your
distribution. If your distribution does not provide a suitable Python
version, you can use [pyenv](https://github.com/yyuu/pyenv) to get a
recent Python environment.
{{< highlight bash >}}
sudo apt install python3-pip # Debian 10 or higher, Ubuntu 17.10 or higher
sudo dnf install python3-pip # Fedora 26 or higher
sudo pacman -S python-pip # Arch Linux
{{< / highlight >}}
Please make sure to upgrade pip3 itself:
{{< highlight bash >}}
sudo pip3 install -U pip
{{< / highlight >}}
Now you can install mitmproxy via pip3:
{{< highlight bash >}}
sudo pip3 install mitmproxy
{{< / highlight >}}
## Installation on Windows via pip3
First, install the latest version of Python 3.6 or higher from the
[Python website](https://www.python.org/downloads/windows/). During
installation, make sure to select Add Python to PATH. There are no other
dependencies on Windows.
Now you can install mitmproxy via pip3:
{{< highlight bash >}}
pip3 install mitmproxy
{{< / highlight >}}
## Installation from Source
If you would like to install mitmproxy directly from source code or the
GitHub master branch, please see the our
[README](https://github.com/mitmproxy/mitmproxy/blob/master/README.rst)
on GitHub.
As a general principle, mitmproxy does not "phone home" and consequently will not do any update checks.