certbot-auto: Print link to doc on debugging pip install error [revision requested] (#3473)

* certbot-auto: Print link to doc on debugging pip install error

Also, update the doc to teach the user to workaround problem on a low
memory system.

* Correct formatting

* grep the PIP_OUT and print useful info if the problem is about memory allocation

* Fix logic on string to grep

docs/install.rst

@@ -73,6 +73,23 @@ For full command line help, you can type::
 
   ./certbot-auto --help all
 
+Problems with Python virtual environment
+----------------------------------------
+
+On a low memory system such as VPS with only 256MB of RAM, the required dependencies of Certbot will failed to build.
+This can be identified if the pip outputs contains something like ``internal compiler error: Killed (program cc1)``.
+You can workaround this restriction by creating a temporary swapfile::
+
+  user@webserver:~$ sudo fallocate -l 1G /tmp/swapfile
+  user@webserver:~$ sudo chmod 600 /tmp/swapfile
+  user@webserver:~$ sudo mkswap /tmp/swapfile
+  user@webserver:~$ sudo swapon /tmp/swapfile
+
+Disable and remove the swapfile once the virtual enviroment is constructed::
+
+  user@webserver:~$ sudo swapoff /tmp/swapfile
+  user@webserver:~$ sudo rm /tmp/swapfile
+
 Running with Docker
 -------------------
 

letsencrypt-auto-source/letsencrypt-auto.template

@@ -285,7 +285,28 @@ UNLIKELY_EOF
       # Report error. (Otherwise, be quiet.)
       echo "Had a problem while installing Python packages."
       if [ "$VERBOSE" != 1 ]; then
+        echo
+        echo "pip prints the following errors: "
+        echo "====================================================="
         echo "$PIP_OUT"
+        echo "====================================================="
+        echo
+        echo "Certbot has problem setting up the virtual environment."
+
+        if `echo $PIP_OUT | grep -q Killed` || `echo $PIP_OUT | grep -q "allocate memory"` ; then
+          echo
+          echo "Based on your pip output, the problem can likely be fixed by "
+          echo "increasing the available memory."
+        else
+          echo
+          echo "We were not be able to guess the right solution from your pip "
+          echo "output."
+        fi
+
+        echo
+        echo "Consult https://certbot.eff.org/docs/install.html#problems-with-python-virtual-environment"
+        echo "for possible solutions."
+        echo "You may also find some support resources at https://certbot.eff.org/support/ ."
       fi
       rm -rf "$VENV_PATH"
       exit 1