From 8a5d199ddffebc0b000b26989a9451f1d12f5639 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Wed, 14 Oct 2015 18:35:34 -0700 Subject: [PATCH] Try to make the "using" instructions as simple and accurate as possible Some of the verbose stuff we had before is really of historical/developer interest only --- docs/contributing.rst | 96 +++++++++++++++++++++++++++++++++++++ docs/using.rst | 109 +++++++++++++++++++----------------------- 2 files changed, 146 insertions(+), 59 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 614f6f2aa..ed74bbb60 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -296,3 +296,99 @@ commands: This should generate documentation in the ``docs/_build/html`` directory. + +Notes on OS depedencies +======================= + +OS level dependencies are managed by scripts in ``bootstrap``. Some notes +are provided here mainly for the :ref:`developers ` reference. + +In general: + +* ``sudo`` is required as a suggested way of running privileged process +* `Augeas`_ is required for the Python bindings +* ``virtualenv`` and ``pip`` are used for managing other python library + dependencies + + +Ubuntu +------ + +.. code-block:: shell + + sudo ./bootstrap/ubuntu.sh + + +Debian +------ + +.. code-block:: shell + + sudo ./bootstrap/debian.sh + +For squeeze you will need to: + +- Use ``virtualenv --no-site-packages -p python`` instead of ``-p python2``. + + +.. _`#280`: https://github.com/letsencrypt/letsencrypt/issues/280 + + +Mac OSX +------- + +.. code-block:: shell + + ./bootstrap/mac.sh + + +Fedora +------ + +.. code-block:: shell + + sudo ./bootstrap/fedora.sh + + +Centos 7 +-------- + +.. code-block:: shell + + sudo ./bootstrap/centos.sh + + +FreeBSD +------- + +.. code-block:: shell + + sudo ./bootstrap/freebsd.sh + +Bootstrap script for FreeBSD uses ``pkg`` for package installation, +i.e. it does not use ports. + +FreeBSD by default uses ``tcsh``. In order to activate virtulenv (see +below), you will need a compatbile shell, e.g. ``pkg install bash && +bash``. + + +Running with Docker +=================== + +Docker_ is another way to quickly obtaintesting 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 auth -it --rm -p 443:443 --name letsencrypt \ + -v "/etc/letsencrypt:/etc/letsencrypt" \ + -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \ + quay.io/letsencrypt/letsencrypt:latest + +and follow the instructions. Your new cert will be available in +``/etc/letsencrypt/certs``. + +.. _Docker: https://docker.com +.. _`install Docker`: https://docs.docker.com/docker/userguide/ diff --git a/docs/using.rst b/docs/using.rst index 3e3973d2f..1920efe38 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -24,17 +24,62 @@ above method instead. .. _prerequisites: -Prerequisites -============= +Installation and Usage +====================== -The demo code is supported and known to work on **Ubuntu and -Debian**. Therefore, prerequisites for other platforms listed below -are provided mainly for the :ref:`developers ` reference. +To install and run the client you just need to type: + +.. code-block:: shell + + ./letsencrypt-auto + +.. warning:: Please do **not** use ``python setup.py install``. That mode of + operation might corrupt your operating system and is **not supported** + by the Let's Encrypt team! + +The ``letsencrypt`` commandline tool has a builtin help: + +.. code-block:: shell + + ./letsencrypt-auto --help + + +Configuration file +------------------ + +It is possible to specify configuration file with +``letsencrypt --config cli.ini`` (or shorter ``-c cli.ini``). For +instance, if you are a contributor, you might find the following +handy: + +.. include:: ../examples/dev-cli.ini + :code: ini + +By default, the following locations are searched: + +- ``/etc/letsencrypt/cli.ini`` +- ``$XDG_CONFIG_HOME/letsencrypt/cli.ini`` (or + ``~/.config/letsencrypt/cli.ini`` if ``$XDG_CONFIG_HOME`` is not + set). + +.. keep it up to date with constants.py + + +.. _Augeas: http://augeas.net/ +.. _Virtualenv: https://virtualenv.pypa.io + +Notes on OS depedencies +======================= + +OS level dependencies are managed by scripts in ``bootstrap``. Some notes +are provided here mainly for the :ref:`developers ` reference. In general: * ``sudo`` is required as a suggested way of running privileged process * `Augeas`_ is required for the Python bindings +* ``virtualenv`` and ``pip`` are used for managing other python library + dependencies Ubuntu @@ -99,61 +144,7 @@ below), you will need a compatbile shell, e.g. ``pkg install bash && bash``. -Installation -============ -.. code-block:: shell - - source ./bootstrap/venv.sh - -.. warning:: Please do **not** use ``python setup.py install``. Please - do **not** attempt the installation commands as - superuser/root and/or without Virtualenv_, e.g. ``sudo - python setup.py install``, ``sudo pip install``, ``sudo - ./venv/bin/...``. These modes of operation might corrupt - your operating system and are **not supported** by the - Let's Encrypt team! - - -Usage -===== - -To get a new certificate run: - -.. code-block:: shell - - (letsencrypt)$ letsencrypt auth - -The ``letsencrypt`` commandline tool has a builtin help: - -.. code-block:: shell - - (letsencrypt)$ letsencrypt --help - - -Configuration file ------------------- - -It is possible to specify configuration file with -``letsencrypt --config cli.ini`` (or shorter ``-c cli.ini``). For -instance, if you are a contributor, you might find the following -handy: - -.. include:: ../examples/dev-cli.ini - :code: ini - -By default, the following locations are searched: - -- ``/etc/letsencrypt/cli.ini`` -- ``$XDG_CONFIG_HOME/letsencrypt/cli.ini`` (or - ``~/.config/letsencrypt/cli.ini`` if ``$XDG_CONFIG_HOME`` is not - set). - -.. keep it up to date with constants.py - - -.. _Augeas: http://augeas.net/ -.. _Virtualenv: https://virtualenv.pypa.io Running with Docker ===================