diff options
author | Noah Swartz <swartzcr@gmail.com> | 2017-03-13 23:48:48 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-03-13 23:48:48 +0300 |
commit | 25bda6177ebc42fc5bc099d270fb50f9ebd19f3a (patch) | |
tree | 60ebc17eebcd2ad472d53e73c75123f7bc08d35c /docs | |
parent | bb35126a2cf76d18187f9c7eec746cd1917c6c37 (diff) | |
parent | 0e735e360c197a1a77e97d806ff4a4a9b90a073a (diff) |
Merge branch 'master' into docs-update-standalone-manual-plugins
Diffstat (limited to 'docs')
-rw-r--r-- | docs/ciphers.rst | 2 | ||||
-rw-r--r-- | docs/cli-help.txt | 2 | ||||
-rw-r--r-- | docs/contributing.rst | 88 | ||||
-rw-r--r-- | docs/using.rst | 17 |
4 files changed, 52 insertions, 57 deletions
diff --git a/docs/ciphers.rst b/docs/ciphers.rst index 31ce45963..1b320cdf9 100644 --- a/docs/ciphers.rst +++ b/docs/ciphers.rst @@ -255,7 +255,7 @@ I have access to an English-language summary of the recommendations. Keylength.com ~~~~~~~~~~~~~ -Damien Giry collects recommendations by academic researchers and standards organizations about keylengths for particular cryptoperiods, years, or security levels. The keylength recommendations of the various sources are summarized in a chart. This site has been updated over time and includes expert guidance from eight sources published between 2000 and 2015. +Damien Giry collects recommendations by academic researchers and standards organizations about keylengths for particular cryptoperiods, years, or security levels. The keylength recommendations of the various sources are summarized in a chart. This site has been updated over time and includes expert guidance from eight sources published between 2000 and 2017. http://www.keylength.com/ diff --git a/docs/cli-help.txt b/docs/cli-help.txt index 4cb408002..9ef9d9e6c 100644 --- a/docs/cli-help.txt +++ b/docs/cli-help.txt @@ -86,7 +86,7 @@ optional arguments: statistics about success rates by OS and plugin. If you wish to hide your server OS version from the Let's Encrypt server, set this to "". (default: - CertbotACMEClient/0.11.1 (Ubuntu 16.04.1 LTS) + CertbotACMEClient/0.12.0 (Ubuntu 16.04.2 LTS) Authenticator/XXX Installer/YYY) automation: diff --git a/docs/contributing.rst b/docs/contributing.rst index 5f939e947..5cdf86147 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -14,15 +14,24 @@ Getting Started Running a local copy of the client ---------------------------------- -Running the client in developer mode from your local tree is a little -different than running ``certbot-auto``. To get set up, do these things -once: +Running the client in developer mode from your local tree is a little different +than running Certbot as a user. To get set up, clone our git repository by +running: .. code-block:: shell git clone https://github.com/certbot/certbot + +If you're on macOS, we recommend you skip the rest of this section and instead +run Certbot in Docker. You can find instructions for how to do this :ref:`here +<docker>`. If you're running on Linux, you can run the following commands to +install dependencies and set up a virtual environment where you can run +Certbot. You only need to do this once. + +.. code-block:: shell + cd certbot - ./letsencrypt-auto-source/letsencrypt-auto --os-packages-only + ./certbot-auto --os-packages-only ./tools/venv.sh Then in each shell where you're working on the client, do: @@ -69,10 +78,8 @@ either in the same directory as ``foo.py`` or in the ``tests`` subdirectory (if there isn't, make one). While you are working on your code and tests, run ``python foo_test.py`` to run the relevant tests. -For debugging, we recommend running ``pip install ipdb`` and putting -``import ipdb; ipdb.set_trace()`` statements inside the source -code. Alternatively, you can use Python's standard library `pdb`, -but you won't get TAB completion. +For debugging, we recommend putting +``import ipdb; ipdb.set_trace()`` statements inside the source code. Once you are done with your code changes, and the tests in ``foo_test.py`` pass, run all of the unittests for Certbot with ``tox -e py27`` (this uses Python @@ -285,8 +292,7 @@ Steps: including coverage. The ``--skip-missing-interpreters`` argument ignores missing versions of Python needed for running the tests. Fix any errors. 5. If your code touches communication with an ACME server/Boulder, you - should run the integration tests, see `integration`_. See `Known Issues`_ - for some common failures that have nothing to do with your code. + should run the integration tests, see `integration`_. 6. Submit the PR. 7. Did your tests pass on Travis? If they didn't, fix any errors. @@ -346,56 +352,36 @@ This should generate documentation in the ``docs/_build/html`` directory. -Other methods for running the client -==================================== +.. _docker: -Vagrant -------- - -If you are a Vagrant user, Certbot comes with a Vagrantfile that -automates setting up a development environment in an Ubuntu 14.04 -LTS VM. To set it up, simply run ``vagrant up``. The repository is -synced to ``/vagrant``, so you can get started with: - -.. code-block:: shell +Running the client with Docker +============================== - vagrant ssh - cd /vagrant - sudo ./venv/bin/certbot +You can use Docker Compose to quickly set up an environment for running and +testing Certbot. This is especially useful for macOS users. To install Docker +Compose, follow the instructions at https://docs.docker.com/compose/install/. -Support for other Linux distributions coming soon. +.. note:: Linux users can simply run ``pip install docker-compose`` to get + Docker Compose after installing Docker Engine and activating your shell as + described in the :ref:`Getting Started <getting_started>` section. -.. note:: - Unfortunately, Python distutils and, by extension, setup.py and - tox, use hard linking quite extensively. Hard linking is not - supported by the default sync filesystem in Vagrant. As a result, - all actions with these commands are *significantly slower* in - Vagrant. One potential fix is to `use NFS`_ (`related issue`_). +Now you can develop on your host machine, but run Certbot and test your changes +in Docker. When using ``docker-compose`` make sure you are inside your clone of +the Certbot repository. As an example, you can run the following command to +check for linting errors:: -.. _use NFS: http://docs.vagrantup.com/v2/synced-folders/nfs.html -.. _related issue: https://github.com/ClusterHQ/flocker/issues/516 + docker-compose run --rm --service-ports development bash -c 'tox -e lint' +You can also leave a terminal open running a shell in the Docker container and +modify Certbot code in another window. The Certbot repo on your host machine is +mounted inside of the container so any changes you make immediately take +effect. To do this, run:: -Docker ------- - -OSX users will probably find it easiest to set up a Docker container for -development. Certbot comes with a Dockerfile (``Dockerfile-dev``) -for doing so. To use Docker on OSX, install and setup docker-machine using the -instructions at https://docs.docker.com/installation/mac/. - -To build the development Docker image:: - - docker build -t certbot -f Dockerfile-dev . - -Now run tests inside the Docker image: - -.. code-block:: shell + docker-compose run --rm --service-ports development bash - docker run -it certbot bash - cd src - tox -e py27 +Now running the check for linting errors described above is as easy as:: + tox -e lint .. _prerequisites: diff --git a/docs/using.rst b/docs/using.rst index c162e2fde..7c17796e7 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -144,6 +144,10 @@ the ``--nginx`` flag on the commandline. Standalone ---------- +Use standalone mode to obtain a cert if you don't want to use (or don't currently have) +existing server software. The standalone plugin does not rely on any other server +software running on the machine where you obtain the cert. + To obtain a cert using a "standalone" webserver, you can use the standalone plugin by including ``certonly`` and ``--standalone`` on the command line. This plugin needs to bind to port 80 or 443 in @@ -154,10 +158,8 @@ one of the options shown below on the command line. * ``--preferred-challenges http`` to use port 80 * ``--preferred-challenges tls-sni`` to use port 443 -The standalone plugin does not rely on any other server software running -on the machine where you obtain the certificate. It must still be possible -for that machine to accept inbound connections from the Internet on the -specified port using each requested domain name. +It must still be possible for your machine to accept inbound connections from +the Internet on the specified port using each requested domain name. .. note:: The ``--standalone-supported-challenges`` option has been deprecated since ``certbot`` version 0.9.0. @@ -429,6 +431,13 @@ Certbot is working hard to improve the renewal process, and we apologize for any inconvenience you encounter in integrating these commands into your individual environment. +.. note:: ``certbot renew`` exit status will only be 1 if a renewal attempt failed. + This means ``certbot renew`` exit status will be 0 if no cert needs to be updated. + If you write a custom script and expect to run a command only after a cert was actually renewed + you will need to use the ``--post-hook`` since the exit status will be 0 both on successful renewal + and when renewal is not necessary. + + Modifying the Renewal Configuration File ---------------------------------------- |