From 4eab094e5e307c8dd862a71de54f0dae3feca2fe Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:23:14 +0000 Subject: [PATCH 01/20] Add dummy Packaging Guide --- docs/index.rst | 1 + docs/packaging.rst | 6 ++++++ 2 files changed, 7 insertions(+) create mode 100644 docs/packaging.rst diff --git a/docs/index.rst b/docs/index.rst index 72be096f9..a7df1fb0f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,6 +7,7 @@ Welcome to the Let's Encrypt client documentation! intro using contributing + packaging plugins .. toctree:: diff --git a/docs/packaging.rst b/docs/packaging.rst new file mode 100644 index 000000000..84d7aa4ca --- /dev/null +++ b/docs/packaging.rst @@ -0,0 +1,6 @@ +========= +Packaging +========= + +Documentation can be found at +https://github.com/letsencrypt/letsencrypt/wiki/Packaging. From 9c98b5c664b2fe408bdb85eb503a04ad64d6760d Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:22:24 +0000 Subject: [PATCH 02/20] Reorg User Guide --- docs/using.rst | 107 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 72 insertions(+), 35 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 883efc78c..74c80887b 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -2,44 +2,95 @@ Using the Let's Encrypt client ============================== +Welcome to the User Guide! -Getting the code -================ +.. contents:: Table of Contents + :local: -Please `install Git`_ and run the following commands: + +Installation +============ + +Unless you have a very specific requirements, we kindly ask you to use +the letsencrypt-auto_ method described below. It's the fastest, the +most thourougly tested and the most reliable way of getting our +software and the free SSL certificates! + +.. letsencrypt-auto: + +letsencrypt-auto +---------------- + +``letsencrypt-auto`` is a wrapper which installs some dependencies +from your OS standard package repostories (e.g using `apt-get` or +`yum`), and for other depencies it sets up a virtualized Python +environment with packages downloaded from PyPI [#venv]_. It also +provides automated updates. + +Firstly, please `install Git`_ and run the following commands: .. code-block:: shell git clone https://github.com/letsencrypt/letsencrypt cd letsencrypt -Alternatively you could `download the ZIP archive`_ and extract the -snapshot of our repository, but it's strongly recommended to use the -above method instead. +.. warning:: Alternatively you could `download the ZIP archive`_ and + extract the snapshot of our repository, but it's strongly + recommended to use the above method instead. .. _`install Git`: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git .. _`download the ZIP archive`: https://github.com/letsencrypt/letsencrypt/archive/master.zip - -Installation and Usage -====================== - To install and run the client you just need to type: .. code-block:: shell ./letsencrypt-auto -(Once letsencrypt is packaged by distributions, the command will just be -``letsencrypt``. ``letsencrypt-auto`` is a wrapper which installs virtualized -dependencies and provides automated updates during the beta program) - -The ``letsencrypt`` commandline tool has a builtin help: +Throughout the documentation, whenever you see references to +``letsencrypt`` script/binary, you can subsitute in +``letsencrypt-auto``. For example, to get the help you would type: .. code-block:: shell - ./letsencrypt-auto --help + ./letsencrypt-auto --help + + +Running with Docker +------------------- + +Docker_ is another way to quickly obtain testing certs. From the +server that the domain your requesting a cert for resolves to, +`install Docker`_, issue the following command: + +.. code-block:: shell + + sudo docker run -it --rm -p 443:443 --name letsencrypt \ + -v "/etc/letsencrypt:/etc/letsencrypt" \ + -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ + quay.io/letsencrypt/letsencrypt:latest auth + +and follow the instructions. Your new cert will be available in +``/etc/letsencrypt/certs``. + +.. _Docker: https://docker.com +.. _`install Docker`: https://docs.docker.com/userguide/ + + +Distro packages +--------------- + +Unfortunately, this is an ongoing effort. If you'd like to package +Let's Encrypt client for your distribution of choice please have a +look at :doc:`packaging`. + + +From source +----------- + +Installation from source is only supported for developers and the +whole process is described in :doc:`contributing`. .. warning:: Please do **not** use ``python setup.py install`` or ``python pip install .``. Please do **not** attempt the @@ -51,7 +102,7 @@ The ``letsencrypt`` commandline tool has a builtin help: Configuration file ------------------- +================== It is possible to specify configuration file with ``letsencrypt-auto --config cli.ini`` (or shorter ``-c cli.ini``). An @@ -70,22 +121,8 @@ By default, the following locations are searched: .. keep it up to date with constants.py -Running with Docker -=================== +.. rubric:: Footnotes -Docker_ is another way to quickly obtain testing certs. From the -server that the domain your requesting a cert for resolves to, -`install Docker`_, issue the following command: - -.. code-block:: shell - - sudo docker run -it --rm -p 443:443 --name letsencrypt \ - -v "/etc/letsencrypt:/etc/letsencrypt" \ - -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ - quay.io/letsencrypt/letsencrypt:latest auth - -and follow the instructions. Your new cert will be available in -``/etc/letsencrypt/certs``. - -.. _Docker: https://docker.com -.. _`install Docker`: https://docs.docker.com/userguide/ +.. [#venv] By using this virtualized Python enviroment (`virtualenv + `_) we don't pollute the main + OS space with packages from PyPI! From 6135fbdc18b4b38903f928ce3720ddaa081a566d Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:26:17 +0000 Subject: [PATCH 03/20] docs: fix prerequisites ref --- docs/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 395493cef..9d40aafd3 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -271,8 +271,6 @@ commands: This should generate documentation in the ``docs/_build/html`` directory. -.. _prerequisites: - Other methods for running the client ==================================== @@ -326,6 +324,8 @@ Now run tests inside the Docker image: tox -e py27 +.. _prerequisites: + Notes on OS dependencies ======================== From c84e9b295073ad247a63eebeff29d109dce5ab0b Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:28:01 +0000 Subject: [PATCH 04/20] Add TOC to dev guide --- docs/contributing.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/contributing.rst b/docs/contributing.rst index 9d40aafd3..161523631 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -2,6 +2,12 @@ Contributing ============ +Welcome to the Developer's Guide! + +.. contents:: Table of Contents + :local: + + .. _hacking: Hacking From d079df9cd5962013ef1cc13bb836f168a0433dae Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:31:41 +0000 Subject: [PATCH 05/20] docs: move plugins.rst to dev guide section --- docs/contributing.rst | 20 ++++++++++++++++++++ docs/index.rst | 1 - docs/plugins.rst | 19 ------------------- 3 files changed, 20 insertions(+), 20 deletions(-) delete mode 100644 docs/plugins.rst diff --git a/docs/contributing.rst b/docs/contributing.rst index 161523631..9166d7d8e 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -214,6 +214,26 @@ plugins implement the `~letsencrypt.interfaces.IDisplay` interface. +Writing your own plugin +======================= + +Let's Encrypt client supports dynamic discovery of plugins through the +`setuptools entry points`_. This way you can, for example, create a +custom implementation of `~letsencrypt.interfaces.IAuthenticator` or +the `~letsencrypt.interfaces.IInstaller` without having to merge it +with the core upstream source code. An example is provided in +``examples/plugins/`` directory. + +.. warning:: Please be aware though that as this client is still in a + developer-preview stage, the API may undergo a few changes. If you + believe the plugin will be beneficial to the community, please + consider submitting a pull request to the repo and we will update + it with any necessary API changes. + +.. _`setuptools entry points`: + https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins + + .. _coding-style: Coding style diff --git a/docs/index.rst b/docs/index.rst index a7df1fb0f..68289d760 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,6 @@ Welcome to the Let's Encrypt client documentation! using contributing packaging - plugins .. toctree:: :maxdepth: 1 diff --git a/docs/plugins.rst b/docs/plugins.rst deleted file mode 100644 index 33d63e84f..000000000 --- a/docs/plugins.rst +++ /dev/null @@ -1,19 +0,0 @@ -======= -Plugins -======= - -Let's Encrypt client supports dynamic discovery of plugins through the -`setuptools entry points`_. This way you can, for example, create a -custom implementation of `~letsencrypt.interfaces.IAuthenticator` or -the `~letsencrypt.interfaces.IInstaller` without having to merge it -with the core upstream source code. An example is provided in -``examples/plugins/`` directory. - -.. warning:: Please be aware though that as this client is still in a - developer-preview stage, the API may undergo a few changes. If you - believe the plugin will be beneficial to the community, please - consider submitting a pull request to the repo and we will update - it with any necessary API changes. - -.. _`setuptools entry points`: - https://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins From 0233f2e9ac233dc9607e1c30372eb382c9213a4b Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:37:25 +0000 Subject: [PATCH 06/20] docs headers: User/Developer/Packaging Guide --- docs/contributing.rst | 8 +++----- docs/packaging.rst | 6 +++--- docs/using.rst | 8 +++----- 3 files changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 9166d7d8e..d0ce2626c 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,8 +1,6 @@ -============ -Contributing -============ - -Welcome to the Developer's Guide! +=============== +Developer Guide +=============== .. contents:: Table of Contents :local: diff --git a/docs/packaging.rst b/docs/packaging.rst index 84d7aa4ca..5f09b65fa 100644 --- a/docs/packaging.rst +++ b/docs/packaging.rst @@ -1,6 +1,6 @@ -========= -Packaging -========= +=============== +Packaging Guide +=============== Documentation can be found at https://github.com/letsencrypt/letsencrypt/wiki/Packaging. diff --git a/docs/using.rst b/docs/using.rst index 74c80887b..cbbce7687 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -1,8 +1,6 @@ -============================== -Using the Let's Encrypt client -============================== - -Welcome to the User Guide! +========== +User Guide +========== .. contents:: Table of Contents :local: From cf26d014cde5654b864b02c617d7fe3f4eba8430 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:40:20 +0000 Subject: [PATCH 07/20] {dev,user,packaging}.rst rename --- CONTRIBUTING.md | 2 +- README.rst | 2 +- bootstrap/install-deps.sh | 2 +- docs/{contributing.rst => dev.rst} | 0 docs/index.rst | 4 ++-- docs/{using.rst => user.rst} | 2 +- letsencrypt-auto | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) rename docs/{contributing.rst => dev.rst} (100%) rename docs/{using.rst => user.rst} (98%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf19b18e1..ac08f0f4e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,4 +15,4 @@ to the Sphinx generated docs is provided below. --> -https://letsencrypt.readthedocs.org/en/latest/contributing.html +https://letsencrypt.readthedocs.org/en/latest/dev.html diff --git a/README.rst b/README.rst index 769bc7a8f..c0d663fe9 100644 --- a/README.rst +++ b/README.rst @@ -68,7 +68,7 @@ server automatically!:: :alt: Docker Repository on Quay.io .. _`installation instructions`: - https://letsencrypt.readthedocs.org/en/latest/using.html + https://letsencrypt.readthedocs.org/en/latest/user.html .. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU diff --git a/bootstrap/install-deps.sh b/bootstrap/install-deps.sh index c159858c5..4785a841f 100755 --- a/bootstrap/install-deps.sh +++ b/bootstrap/install-deps.sh @@ -34,7 +34,7 @@ else echo "Sorry, I don't know how to bootstrap Let's Encrypt on your operating system!" echo echo "You will need to bootstrap, configure virtualenv, and run a pip install manually" - echo "Please see https://letsencrypt.readthedocs.org/en/latest/contributing.html#prerequisites" + echo "Please see https://letsencrypt.readthedocs.org/en/latest/dev.html#prerequisites" echo "for more info" exit 1 fi diff --git a/docs/contributing.rst b/docs/dev.rst similarity index 100% rename from docs/contributing.rst rename to docs/dev.rst diff --git a/docs/index.rst b/docs/index.rst index 68289d760..9c4c40807 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,8 +5,8 @@ Welcome to the Let's Encrypt client documentation! :maxdepth: 2 intro - using - contributing + user + dev packaging .. toctree:: diff --git a/docs/using.rst b/docs/user.rst similarity index 98% rename from docs/using.rst rename to docs/user.rst index cbbce7687..9fd4f4e75 100644 --- a/docs/using.rst +++ b/docs/user.rst @@ -88,7 +88,7 @@ From source ----------- Installation from source is only supported for developers and the -whole process is described in :doc:`contributing`. +whole process is described in :doc:`dev`. .. warning:: Please do **not** use ``python setup.py install`` or ``python pip install .``. Please do **not** attempt the diff --git a/letsencrypt-auto b/letsencrypt-auto index 5b974c1f8..8df5eda81 100755 --- a/letsencrypt-auto +++ b/letsencrypt-auto @@ -55,7 +55,7 @@ then echo "Sorry, I don't know how to bootstrap Let's Encrypt on your operating system!" echo echo "You will need to bootstrap, configure virtualenv, and run a pip install manually" - echo "Please see https://letsencrypt.readthedocs.org/en/latest/contributing.html#prerequisites" + echo "Please see https://letsencrypt.readthedocs.org/en/latest/dev.html#prerequisites" echo "for more info" fi From 6ef9f89c99dfa1b39cdd78bff8a429ae20656c02 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 19:52:54 +0000 Subject: [PATCH 08/20] Add plugins section to user guide --- docs/dev.rst | 1 + docs/user.rst | 9 +++++++++ 2 files changed, 10 insertions(+) diff --git a/docs/dev.rst b/docs/dev.rst index d0ce2626c..5f2a84605 100644 --- a/docs/dev.rst +++ b/docs/dev.rst @@ -211,6 +211,7 @@ We currently offer a pythondialog and "text" mode for displays. Display plugins implement the `~letsencrypt.interfaces.IDisplay` interface. +.. _dev-plugin: Writing your own plugin ======================= diff --git a/docs/user.rst b/docs/user.rst index 9fd4f4e75..fa4008e8c 100644 --- a/docs/user.rst +++ b/docs/user.rst @@ -99,6 +99,15 @@ whole process is described in :doc:`dev`. Let's Encrypt team! +Plugins +======= + +Third party plugins are listed at +https://github.com/letsencrypt/letsencrypt/wiki/Plugins. If that +that's not enough, you can always :ref:`write your own plugin +`. + + Configuration file ================== From dd254c3a9b2ac1dbb2a4db51679133901ccadfc6 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 20:20:35 +0000 Subject: [PATCH 09/20] Add plugins table to docs --- docs/user.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/user.rst b/docs/user.rst index fa4008e8c..81b2320c4 100644 --- a/docs/user.rst +++ b/docs/user.rst @@ -102,6 +102,27 @@ whole process is described in :doc:`dev`. Plugins ======= +Officially supported plugins: + +========== = = ================================================================ +Plugin A I Notes and status +========== = = ================================================================ +standalone Y N Very stable. Uses port 80 (force by + ``--standalone-supported-challenges simpleHttp``) or 443 + (force by ``statndalone-supported-challenges dvsni``). +webroot Y N Works with already running webserver, by writing necessary files + to the disk (``--webroot-path`` should be pointed to your + ``public_html``). Currently, when multiple domains are specified + (`-d`), they must all use the same web root path. +manual Y N Hidden from standard UI, use with ``--a manual``. Requires to + copy and paste commands into a new terminal session. Allows to + run client on machine different than target webserver, e.g. your + laptop. +apache Y Y Alpha - might break stuff, so be careful. Support for + Debian-derived distros only. +nginx Y Y Very experimental. Not included in letsencrypt-auto_. +========== = = ================================================================ + Third party plugins are listed at https://github.com/letsencrypt/letsencrypt/wiki/Plugins. If that that's not enough, you can always :ref:`write your own plugin From eee217acd307014347a53b94c6d3b15e93169ab2 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 21:23:47 +0000 Subject: [PATCH 10/20] Fix link to letsencrypt-auto --- docs/user.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user.rst b/docs/user.rst index 81b2320c4..3af49f259 100644 --- a/docs/user.rst +++ b/docs/user.rst @@ -14,7 +14,7 @@ the letsencrypt-auto_ method described below. It's the fastest, the most thourougly tested and the most reliable way of getting our software and the free SSL certificates! -.. letsencrypt-auto: +.. _letsencrypt-auto: letsencrypt-auto ---------------- From 007969151be45e004d3e13dd9eac778bd9832a59 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sat, 24 Oct 2015 21:24:09 +0000 Subject: [PATCH 11/20] Add "Getting help" section to User Guide --- docs/user.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/user.rst b/docs/user.rst index 3af49f259..913a3de1f 100644 --- a/docs/user.rst +++ b/docs/user.rst @@ -5,6 +5,7 @@ User Guide .. contents:: Table of Contents :local: +.. _installation: Installation ============ @@ -154,3 +155,25 @@ By default, the following locations are searched: .. [#venv] By using this virtualized Python enviroment (`virtualenv `_) we don't pollute the main OS space with packages from PyPI! + + +Getting help +============ + +If you're having problems you can chat with us on `IRC (#letsencrypt @ +Freenode) `_ or +get support on our `forums `_. + +If you find a bug in the software, please do report it in our `issue +tracker +`_. Remember to +give us us as much information as possible: + +- copy and paste exact command line used and the output (though mind + that the latter might include some personally identifiable + information, including your email and domains) +- copy and paste logs from ``/var/log/letsencrypt`` (though mind they + also might contain personally identifiable information) +- copy and paste ``letsencrypt --version`` output +- your operating system, including specific version +- specify which installation_ method you've chosen From ae9e5f7fff94741e52a3f183b940fad4e7f762b5 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sun, 25 Oct 2015 10:14:40 +0000 Subject: [PATCH 12/20] Revert to {using,contributing}.rst --- CONTRIBUTING.md | 2 +- README.rst | 2 +- bootstrap/install-deps.sh | 2 +- docs/{dev.rst => contributing.rst} | 0 docs/index.rst | 4 ++-- docs/{user.rst => using.rst} | 2 +- letsencrypt-auto | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) rename docs/{dev.rst => contributing.rst} (100%) rename docs/{user.rst => using.rst} (99%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ac08f0f4e..bf19b18e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,4 +15,4 @@ to the Sphinx generated docs is provided below. --> -https://letsencrypt.readthedocs.org/en/latest/dev.html +https://letsencrypt.readthedocs.org/en/latest/contributing.html diff --git a/README.rst b/README.rst index c0d663fe9..769bc7a8f 100644 --- a/README.rst +++ b/README.rst @@ -68,7 +68,7 @@ server automatically!:: :alt: Docker Repository on Quay.io .. _`installation instructions`: - https://letsencrypt.readthedocs.org/en/latest/user.html + https://letsencrypt.readthedocs.org/en/latest/using.html .. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU diff --git a/bootstrap/install-deps.sh b/bootstrap/install-deps.sh index 4785a841f..c159858c5 100755 --- a/bootstrap/install-deps.sh +++ b/bootstrap/install-deps.sh @@ -34,7 +34,7 @@ else echo "Sorry, I don't know how to bootstrap Let's Encrypt on your operating system!" echo echo "You will need to bootstrap, configure virtualenv, and run a pip install manually" - echo "Please see https://letsencrypt.readthedocs.org/en/latest/dev.html#prerequisites" + echo "Please see https://letsencrypt.readthedocs.org/en/latest/contributing.html#prerequisites" echo "for more info" exit 1 fi diff --git a/docs/dev.rst b/docs/contributing.rst similarity index 100% rename from docs/dev.rst rename to docs/contributing.rst diff --git a/docs/index.rst b/docs/index.rst index 9c4c40807..68289d760 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -5,8 +5,8 @@ Welcome to the Let's Encrypt client documentation! :maxdepth: 2 intro - user - dev + using + contributing packaging .. toctree:: diff --git a/docs/user.rst b/docs/using.rst similarity index 99% rename from docs/user.rst rename to docs/using.rst index 913a3de1f..9632c17d1 100644 --- a/docs/user.rst +++ b/docs/using.rst @@ -89,7 +89,7 @@ From source ----------- Installation from source is only supported for developers and the -whole process is described in :doc:`dev`. +whole process is described in :doc:`contributing`. .. warning:: Please do **not** use ``python setup.py install`` or ``python pip install .``. Please do **not** attempt the diff --git a/letsencrypt-auto b/letsencrypt-auto index 8df5eda81..5b974c1f8 100755 --- a/letsencrypt-auto +++ b/letsencrypt-auto @@ -55,7 +55,7 @@ then echo "Sorry, I don't know how to bootstrap Let's Encrypt on your operating system!" echo echo "You will need to bootstrap, configure virtualenv, and run a pip install manually" - echo "Please see https://letsencrypt.readthedocs.org/en/latest/dev.html#prerequisites" + echo "Please see https://letsencrypt.readthedocs.org/en/latest/contributing.html#prerequisites" echo "for more info" fi From 6b69095c8b6a54b04159312567f2e2d8028c1ad2 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sun, 25 Oct 2015 10:27:09 +0000 Subject: [PATCH 13/20] Move footnotes to the bottom --- docs/using.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 9632c17d1..951f7875f 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -150,13 +150,6 @@ By default, the following locations are searched: .. keep it up to date with constants.py -.. rubric:: Footnotes - -.. [#venv] By using this virtualized Python enviroment (`virtualenv - `_) we don't pollute the main - OS space with packages from PyPI! - - Getting help ============ @@ -177,3 +170,10 @@ give us us as much information as possible: - copy and paste ``letsencrypt --version`` output - your operating system, including specific version - specify which installation_ method you've chosen + + +.. rubric:: Footnotes + +.. [#venv] By using this virtualized Python enviroment (`virtualenv + `_) we don't pollute the main + OS space with packages from PyPI! From a2d5527c5a1d514b87cd9951a24ca3bcfd157a68 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sun, 25 Oct 2015 10:28:55 +0000 Subject: [PATCH 14/20] *the* X Guide --- docs/using.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 951f7875f..794b8866a 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -82,14 +82,14 @@ Distro packages Unfortunately, this is an ongoing effort. If you'd like to package Let's Encrypt client for your distribution of choice please have a -look at :doc:`packaging`. +look at the :doc:`packaging`. From source ----------- Installation from source is only supported for developers and the -whole process is described in :doc:`contributing`. +whole process is described in the :doc:`contributing`. .. warning:: Please do **not** use ``python setup.py install`` or ``python pip install .``. Please do **not** attempt the From d456771698add31fcfaddfffbec5eb310e97da4b Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sun, 25 Oct 2015 11:01:20 +0000 Subject: [PATCH 15/20] Fix typos --- docs/using.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 794b8866a..f747fa389 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -12,7 +12,7 @@ Installation Unless you have a very specific requirements, we kindly ask you to use the letsencrypt-auto_ method described below. It's the fastest, the -most thourougly tested and the most reliable way of getting our +most thoroughly tested and the most reliable way of getting our software and the free SSL certificates! .. _letsencrypt-auto: @@ -21,8 +21,8 @@ letsencrypt-auto ---------------- ``letsencrypt-auto`` is a wrapper which installs some dependencies -from your OS standard package repostories (e.g using `apt-get` or -`yum`), and for other depencies it sets up a virtualized Python +from your OS standard package repositories (e.g using `apt-get` or +`yum`), and for other dependencies it sets up a virtualized Python environment with packages downloaded from PyPI [#venv]_. It also provides automated updates. @@ -48,7 +48,7 @@ To install and run the client you just need to type: ./letsencrypt-auto Throughout the documentation, whenever you see references to -``letsencrypt`` script/binary, you can subsitute in +``letsencrypt`` script/binary, you can substitute in ``letsencrypt-auto``. For example, to get the help you would type: .. code-block:: shell @@ -110,7 +110,7 @@ Plugin A I Notes and status ========== = = ================================================================ standalone Y N Very stable. Uses port 80 (force by ``--standalone-supported-challenges simpleHttp``) or 443 - (force by ``statndalone-supported-challenges dvsni``). + (force by ``standalone-supported-challenges dvsni``). webroot Y N Works with already running webserver, by writing necessary files to the disk (``--webroot-path`` should be pointed to your ``public_html``). Currently, when multiple domains are specified @@ -174,6 +174,6 @@ give us us as much information as possible: .. rubric:: Footnotes -.. [#venv] By using this virtualized Python enviroment (`virtualenv +.. [#venv] By using this virtualized Python environment (`virtualenv `_) we don't pollute the main OS space with packages from PyPI! From ce4452d65b15d58fff14b1862184b4193dd414d7 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sun, 25 Oct 2015 11:30:46 +0000 Subject: [PATCH 16/20] Add "Where are my certificates?" to docs (fixes #608). --- docs/using.rst | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/using.rst b/docs/using.rst index f747fa389..9db616387 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -130,6 +130,73 @@ that's not enough, you can always :ref:`write your own plugin `. +Where are my certificates? +========================== + +First of all, we encourage you to use Apache or nginx installers, both +which perform the certificate managemant automatically. If, however, +you prefer to manage everything by hand, this section provides +information on where to find necessary files. + +All generated keys and issued certificates can be found in +``/etc/letsencrypt/live/$domain``. Rather than copying, please point +your (web) server configuration directly to those files (or create +symlinks). During the renewal_, ``/etc/letsencrypt/live`` is updated +with the latest necessary files. + +.. note:: ``/etc/letsencrypt/archive`` and ``/etc/letsencrypt/keys`` + contain all previous keys and certificates, while + ``/etc/letsencrypt/live`` symlinks to the latest versions. + +The following files are available: + +``privkey.pem`` + Private key for the certificate. + + .. warning:: This **must be kept secret at all times**! Never share + it with anyone, including Let's Encrypt developers. You cannot + put it into safe, however - your server still needs to access + this file in order for SSL/TLS to work. + + This is what Apache needs for `SSLCertificateKeyFile + `_, + and nginx for `ssl_certificate_key + `_. + +``cert.pem`` + Server certificate only. + + This is what Apache needs for `SSLCertificateFile + `_. + +``chain.pem`` + All certificates that need to be served by the browser **excluding** + server certificate, i.e. root and intermediate certificates only. + + This is what Apache needs for `SSLCertificateChainFile + `_. + +``fullchain.pem`` + All certificates, **including** server certificate. This is + concatenation of ``chain.pem`` and ``cert.pem``. + + This is what nginx needs for `ssl_certificate + `_. + + +For both chain files, all certificates are ordered from root (primary +certificate) towards leaf. + +Please note, that **you must use** either ``chain.pem`` or +``fullchain.pem``. In case of webservers, using only ``cert.pem``, +will cause nasty errors served through the browsers! + +.. note:: All files are PEM-encoded (as the filename suffix + suggests). If you need other format, such as DER or PFX, then you + could convert using ``openssl``, but this means you will not + benefit from automatic renewal_! + + Configuration file ================== From 38036b758c77b82ee64d1195ea70391ad3947d41 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sun, 25 Oct 2015 12:15:03 +0000 Subject: [PATCH 17/20] Add basic docs on renewal (fixes #951). --- docs/using.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/using.rst b/docs/using.rst index 9db616387..04b0a7432 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -130,6 +130,25 @@ that's not enough, you can always :ref:`write your own plugin `. +Renewal +======= + +.. note:: Let's Encrypt CA issues short lived certificates (90 + days). Make sure you renew the certificates at least once in 3 + months. + +In order to renew certificates simply call the ``letsencrypt`` (or +letsencrypt-auto_) again, and use the same values when prompted. You +can automate it slightly by passing necessary flags on the CLI (see +`--help all`), or even further using the :ref:`config-file`. If you're +sure that UI doesn't prompt for any details you can add the command to +``crontab`` (make it less than every 90 days to avoid problems, say +every month). + +Let's Encrypt is working hard on automating the renewal process. Until +the tool is ready, we are sorry for the inconvenience! + + Where are my certificates? ========================== @@ -197,6 +216,8 @@ will cause nasty errors served through the browsers! benefit from automatic renewal_! +.. _config-file: + Configuration file ================== From c43825fd35f9d8b7b3de24db50396c1756047538 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Sun, 25 Oct 2015 12:35:26 +0000 Subject: [PATCH 18/20] Explain Docker limitations (fixes #1000). --- docs/using.rst | 26 +++++++++++++++++++++----- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 04b0a7432..a1029351d 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -59,9 +59,22 @@ Throughout the documentation, whenever you see references to Running with Docker ------------------- -Docker_ is another way to quickly obtain testing certs. From the -server that the domain your requesting a cert for resolves to, -`install Docker`_, issue the following command: +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. + +You should definitely read the :ref:`where-certs` section, in order to +know how to manage the certs +manually. https://github.com/letsencrypt/letsencrypt/wiki/Ciphersuite-guidance +provides some information about recommended ciphersuites. If none of +these make much sense to you, you should definitely use the +letsencrypt-auto_ method, which enables you to use installer plugins +that cover both of those hard topics. + +If you're still not convinced and have decided to use this method, +from the server that the domain your requesting a cert for resolves +to, `install Docker`_, issue the following command: .. code-block:: shell @@ -70,8 +83,9 @@ server that the domain your requesting a cert for resolves to, -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ quay.io/letsencrypt/letsencrypt:latest auth -and follow the instructions. Your new cert will be available in -``/etc/letsencrypt/certs``. +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. .. _Docker: https://docker.com .. _`install Docker`: https://docs.docker.com/userguide/ @@ -149,6 +163,8 @@ Let's Encrypt is working hard on automating the renewal process. Until the tool is ready, we are sorry for the inconvenience! +.. _where-certs: + Where are my certificates? ========================== From ca777a300fca1351dace916307e0529632aa5501 Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Mon, 26 Oct 2015 18:58:16 +0000 Subject: [PATCH 19/20] Comparison of different installation methods --- docs/using.rst | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index a1029351d..73d0aea64 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -10,11 +10,6 @@ User Guide Installation ============ -Unless you have a very specific requirements, we kindly ask you to use -the letsencrypt-auto_ method described below. It's the fastest, the -most thoroughly tested and the most reliable way of getting our -software and the free SSL certificates! - .. _letsencrypt-auto: letsencrypt-auto @@ -114,6 +109,15 @@ whole process is described in the :doc:`contributing`. Let's Encrypt team! +Comparison of different methods +------------------------------- + +Unless you have a very specific requirements, we kindly ask you to use +the letsencrypt-auto_ method. It's the fastest, the most thoroughly +tested and the most reliable way of getting our software and the free +SSL certificates! + + Plugins ======= From bbea646078ed510b6849001478430f1b1024ecfc Mon Sep 17 00:00:00 2001 From: Jakub Warmuz Date: Mon, 26 Oct 2015 19:00:06 +0000 Subject: [PATCH 20/20] docs: better apache desc + move to 2nd place --- docs/using.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/using.rst b/docs/using.rst index 73d0aea64..cf4d4fe90 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -129,6 +129,8 @@ Plugin A I Notes and status standalone Y N Very stable. Uses port 80 (force by ``--standalone-supported-challenges simpleHttp``) or 443 (force by ``standalone-supported-challenges dvsni``). +apache Y Y Alpha. Automates Apache installation, works fairly well but on + Debian-based distributions only for now. webroot Y N Works with already running webserver, by writing necessary files to the disk (``--webroot-path`` should be pointed to your ``public_html``). Currently, when multiple domains are specified @@ -137,8 +139,6 @@ manual Y N Hidden from standard UI, use with ``--a manual``. Requires to copy and paste commands into a new terminal session. Allows to run client on machine different than target webserver, e.g. your laptop. -apache Y Y Alpha - might break stuff, so be careful. Support for - Debian-derived distros only. nginx Y Y Very experimental. Not included in letsencrypt-auto_. ========== = = ================================================================