From c92a1cd182f4ad15e40552777648621b08dab486 Mon Sep 17 00:00:00 2001 From: Peter Date: Thu, 7 Jul 2016 17:24:58 -0700 Subject: [PATCH 1/3] Clarifications to Docker, certbot-auto content reflecting first three questions in my comment https://github.com/certbot/certbot/pull/3232#issuecomment-231154320 --- docs/using.rst | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 806dfb340..1d9dc0c32 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -8,14 +8,16 @@ User Guide Getting Certbot =============== -To get specific instructions for installing Certbot on your OS, we recommend -visiting certbot.eff.org_. If you're offline, you can find some general +To get specific instructions for installing Certbot on your OS, +visit certbot.eff.org_. This is the easiest way to install Certbot. + +If you're offline, or if your webserver or OS are not in the menu, you can find some general instructions `in the README / Introduction `__ __ installation_ .. _certbot.eff.org: https://certbot.eff.org -.. _certbot-auto: +.. _certbot-auto: https://certbot.eff.org/docs/using.html#certbot-auto The name of the certbot command ------------------------------- @@ -394,7 +396,12 @@ Running with Docker Docker_ is an amazingly simple and quick way to obtain a certificate. However, this mode of operation is unable to install certificates or configure your webserver, because our installer -plugins cannot reach it from inside the Docker container. +plugins cannot reach your webserver from inside the Docker container. + +Most users should use the operating system packages (available from +certbot.eff.org_) or, as a fallback, ``certbot-auto``. You should only +use Docker if you are sure you know what you are doing and have a +good reason to do so. You should definitely read the :ref:`where-certs` section, in order to know how to manage the certs @@ -415,9 +422,13 @@ to, `install Docker`_, then issue the following command: -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ quay.io/letsencrypt/letsencrypt:latest auth -and follow the instructions (note that ``auth`` command is explicitly -used - no installer plugins involved). Your new cert will be available -in ``/etc/letsencrypt/live`` on the host. +Certbot will obtain a certificate and place it in the directory +``/etc/letsencrypt/live`` on your system and display further instructions +for installing the certificates. You must use the ``auth`` command +to install the certificates instead of plug-ins for this method. + +For more information about the layout +of the ``/etc/letsencrypt`` directory, see :ref:`where-certs`. .. _Docker: https://docker.com .. _`install Docker`: https://docs.docker.com/userguide/ @@ -543,10 +554,10 @@ whole process is described in the :doc:`contributing`. Comparison of different methods ------------------------------- -Unless you have a very specific requirements, we kindly suggest that you use -the certbot-auto_ method. It's the fastest, the most thoroughly -tested and the most reliable way of getting our software and the free -TLS/SSL certificates! +Unless you have very specific requirements, we kindly suggest that you use +the Certbot packages provided by your package manager (see certbot.eff.org_). +If such packages are not available, we recommend using ``certbot-auto``, which +automates the process of installing Certbot on your system. Beyond the methods discussed here, other methods may be possible, such as installing Certbot directly with pip from PyPI or downloading a ZIP From 640bb88d4f6ef735f3269563cb388e7c33d9df82 Mon Sep 17 00:00:00 2001 From: Peter Date: Fri, 15 Jul 2016 14:56:03 -0700 Subject: [PATCH 2/3] Fixes in response to Brad's comments at https://github.com/certbot/certbot/pull/3258 --- docs/using.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 1d9dc0c32..f56583a5f 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -9,9 +9,10 @@ Getting Certbot =============== To get specific instructions for installing Certbot on your OS, -visit certbot.eff.org_. This is the easiest way to install Certbot. +visit certbot.eff.org_. This is the easiest way to learn how to get +Certbot up and running on your system. -If you're offline, or if your webserver or OS are not in the menu, you can find some general +If you're offline, you can find some general instructions `in the README / Introduction `__ __ installation_ @@ -398,7 +399,7 @@ certificate. However, this mode of operation is unable to install certificates or configure your webserver, because our installer plugins cannot reach your webserver from inside the Docker container. -Most users should use the operating system packages (available from +Most users should use the operating system packages (see instructions at certbot.eff.org_) or, as a fallback, ``certbot-auto``. You should only use Docker if you are sure you know what you are doing and have a good reason to do so. @@ -420,12 +421,12 @@ to, `install Docker`_, then issue the following command: sudo docker run -it --rm -p 443:443 -p 80:80 --name certbot \ -v "/etc/letsencrypt:/etc/letsencrypt" \ -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ - quay.io/letsencrypt/letsencrypt:latest auth + quay.io/letsencrypt/letsencrypt:latest certonly Certbot will obtain a certificate and place it in the directory -``/etc/letsencrypt/live`` on your system and display further instructions -for installing the certificates. You must use the ``auth`` command -to install the certificates instead of plug-ins for this method. +``/etc/letsencrypt/live`` on your system. +You must use the ``certonly`` command +to install the certificate. For more information about the layout of the ``/etc/letsencrypt`` directory, see :ref:`where-certs`. From 69d3e56f1bc62cc94d8ff0e957105bd78fba3bc6 Mon Sep 17 00:00:00 2001 From: Peter Date: Fri, 15 Jul 2016 16:43:41 -0700 Subject: [PATCH 3/3] Final quick fixes in response to Brad's comments at https://github.com/certbot/certbot/pull/3258 --- docs/using.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index f56583a5f..ccd1d8f97 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -423,10 +423,10 @@ to, `install Docker`_, then issue the following command: -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ quay.io/letsencrypt/letsencrypt:latest certonly -Certbot will obtain a certificate and place it in the directory -``/etc/letsencrypt/live`` on your system. -You must use the ``certonly`` command -to install the certificate. +Running Certbot with the ``certonly`` command will obtain a certificate and place it in the directory +``/etc/letsencrypt/live`` on your system. Because Certonly cannot install the certificate from +within Docker, you must install the certificate manually according to the procedure +recommended by the provider of your webserver. For more information about the layout of the ``/etc/letsencrypt`` directory, see :ref:`where-certs`.