mirror of
https://github.com/Grasscutters/mitmproxy.git
synced 2024-11-22 15:37:45 +00:00
Merge pull request #3718 from mhils/simplify-install-instructions
Simplify install instructions
This commit is contained in:
Maximilian Hils
GitHub
commit
bbb7eb692f
24
README.rst
24
README.rst
@ -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.
|
||||
|
||||
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user