update linux install docs and release instructions (#3746)

* update linux install docs and release instructions

* rhel/centos is so bad they don't even have python3

2 files changed, 52 insertions, 15 deletions

diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst
index da25d45d..5d96a49e 100644
--- a/docs/doing-a-release.rst
+++ b/docs/doing-a-release.rst
@@ -6,9 +6,11 @@ Doing a release of ``cryptography`` requires a few steps.
 Verifying and upgrading OpenSSL version
 ---------------------------------------
 
-The release process uses a static build for Windows and macOS wheels. Check
-that the Windows and macOS Jenkins builders have the latest version of OpenSSL
-installed before performing the release. If they do not:
+The release process creates wheels bundling OpenSSL for Windows, macOS, and
+Linux. Check that the Windows and macOS Jenkins builders have the latest
+version of OpenSSL installed and verify that the latest version is present in
+the ``pyca/cryptography-manylinux1`` docker containers. If anything is out
+of date:
 
 Upgrading Windows
 ~~~~~~~~~~~~~~~~~
@@ -21,6 +23,13 @@ Upgrading macOS
 
 Run the ``update-brew-openssl`` Jenkins job.
 
+Upgrading ``manylinux1`` docker containers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Send a pull request to the ``pyca/infra`` project updating the version and
+file hash in ``cryptography-manylinux1/install_openssl.sh``. Once this is
+merged the updated image will be available to the wheel builder.
+
 Bumping the version number
 --------------------------
 
diff --git a/docs/installation.rst b/docs/installation.rst
index 0fa986a1..01ac2d94 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -18,6 +18,7 @@ PyPy 5.3+ on these operating systems.
 * macOS 10.12 Sierra, 10.11 El Capitan, 10.10 Yosemite, 10.9 Mavericks
 * x86-64 Ubuntu 14.04, 16.04, and rolling
 * x86-64 Debian Wheezy (7.x), Jessie (8.x), Stretch (9.x), and Sid (unstable)
+* x86-64 Alpine (latest)
 * 32-bit and 64-bit Python on 64-bit Windows Server 2012
 
 .. warning::
@@ -74,31 +75,58 @@ local `wheel cache`_.
 Building cryptography on Linux
 ------------------------------
 
-``cryptography`` should build very easily on Linux provided you have a C
-compiler, headers for Python (if you're not using ``pypy``), and headers for
-the OpenSSL and ``libffi`` libraries available on your system.
+``cryptography`` ships a ``manylinux1`` wheel (as of 2.0) so all dependencies
+are included. For users on pip 8.1 or above running on a ``manylinux1``
+compatible distribution (almost everything except Alpine) all you should
+need to do is:
 
-For Debian and Ubuntu, the following command will ensure that the required
-dependencies are installed (replace ``python-dev`` with ``python3-dev`` if
-you're using Python 3):
+.. code-block:: console
+
+    $ pip install cryptography
+
+If you are on Alpine or just want to compile it yourself then
+``cryptography`` requires a compiler, headers for Python (if you're not
+using ``pypy``), and headers for the OpenSSL and ``libffi`` libraries
+available on your system.
+
+Alpine
+~~~~~~
+
+Replace ``python3-dev`` with ``python-dev`` if you're using Python 2.
+
+.. code-block:: console
+
+    $ sudo apk add gcc musl-dev python3-dev libffi-dev openssl-dev
+
+If you get an error with ``openssl-dev`` you may have to use ``libressl-dev``.
+
+Debian/Ubuntu
+~~~~~~~~~~~~~
+
+Replace ``python3-dev`` with ``python-dev`` if you're using Python 2.
 
 .. code-block:: console
 
-    $ sudo apt-get install build-essential libssl-dev libffi-dev python-dev
+    $ sudo apt-get install build-essential libssl-dev libffi-dev python3-dev
 
-For Fedora and RHEL-derivatives, the following command will ensure that the
-required dependencies are installed (replace ``python-devel`` with
-``python3-devel`` if you're using Python 3):
+RHEL/CentOS
+~~~~~~~~~~~
 
 .. code-block:: console
 
     $ sudo yum install gcc libffi-devel python-devel openssl-devel
 
-You should now be able to build and install cryptography with the usual
+
+Building
+~~~~~~~~
+
+You should now be able to build and install cryptography. To avoid getting
+the pre-built wheel on ``manylinux1`` distributions you'll need to use
+``--no-binary``.
 
 .. code-block:: console
 
-    $ pip install cryptography
+    $ pip install cryptography --no-binary cryptography
 
 
 Using your own OpenSSL on Linux