crypt/certbot
1
0
Fork 0
mirror of https://github.com/certbot/certbot.git synced 2026-01-23 07:20:55 +03:00
Code Activity

Merge branch 'docs' of git://github.com/ThomasWaldmann/lets-encrypt-preview into ThomasWaldmann-docs

Browse Source
This commit is contained in:
James Kasten
2015-01-26 22:45:25 -08:00
parent 8c80d0bedf fb2d8061c8
commit 8a46c39fec
9 changed files with 268 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.travis.yml
View File

@@ -1,4 +1,4 @@
# To mimic README.md installation and hacking instructions as much as
# To mimic README.rst installation and hacking instructions as much as
# possible, this config file instructs Travis CI to create a build
# environment for each supported Python version, and then for each of
# those it runs tox with two environments: lint and pyXX corresponding

27
CHANGES.rst Normal file
View File

@@ -0,0 +1,27 @@
ChangeLog
=========
Please note:
the change log will only get updated after first release - for now please use the
`commit log <https://github.com/letsencrypt/lets-encrypt-preview/commits/master>`_.
Release 0.1.0 (not released yet)
--------------------------------
New Features:
* ...
Fixes:
* ...
Other changes:
* ...
Release 0.0.0 (not released yet)
--------------------------------
Initial release.

143
README.md
View File

@@ -1,143 +0,0 @@
# Let's Encrypt
[![Build Status]
(https://travis-ci.org/letsencrypt/lets-encrypt-preview.svg?branch=master)]
(https://travis-ci.org/letsencrypt/lets-encrypt-preview)
## Disclaimer
This is the [Let's Encrypt] Agent **DEVELOPER PREVIEW** repository.
**DO NOT RUN THIS CODE ON A PRODUCTION WEBSERVER. IT WILL INSTALL
CERTIFICATES SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR
USERS.**
This code is intended for testing, demonstration, and integration
engineering with OSes and hosting platforms. For the time being
project focuses on Linux and Apache, though we will be expanding
it to other platforms.
## Running the demo code
The demo code is supported and known to work on **Ubuntu only** (even
closely related [Debian is known to fail]
(https://github.com/letsencrypt/lets-encrypt-preview/issues/68)).
Therefore, prerequisites for other platforms listed below are provided
mainly for the [developers](#hacking) reference.
### Prerequisites
In general:
* [swig] is required for compiling [m2crypto]
* [augeas] is required for the `python-augeas` bindings
#### Ubuntu
```
sudo apt-get install python python-setuptools python-virtualenv \
python-dev gcc swig dialog libaugeas0 libssl-dev ca-certificates
```
#### Mac OSX
`sudo brew install augeas swig`
### Installation
```
virtualenv --no-site-packages -p python2 venv
./venv/bin/python setup.py install
sudo ./venv/bin/letsencrypt
```
## Hacking
In order to start hacking, you will first have to create a development
environment:
`./venv/bin/python setup.py dev`
The code base, including your pull requests, **must have 100% test
statement coverage and be compliant with the [coding
style](#coding-style)**. The following tools are there to help you:
- `./venv/bin/tox` starts a full set of tests. Please make sure you
run it before submitting a new pull request.
- `./venv/bin/tox -e cover` checks the test coverage only.
- `./venv/bin/tox -e lint` checks the style of the whole project,
while `./venv/bin/pylint --rcfile=.pylintrc file` will check a single `file` only.
## Documentation
The official documentation is available at
https://letsencrypt.readthedocs.org.
In order to generate the Sphinx documentation, run the following
commands.
```
./venv/bin/python setup.py docs
cd docs
make clean html SPHINXBUILD=../venv/bin/sphinx-build
```
This should generate documentation in the `docs/_build/html`
directory.
### Coding style
Most importantly, **be consistent with the rest of the code**, please.
1. Read [PEP 8 - Style Guide for Python Code]
(https://www.python.org/dev/peps/pep-0008).
2. Follow [Google Python Style Guide]
(https://google-styleguide.googlecode.com/svn/trunk/pyguide.html),
with the exception that we use [Sphinx](http://sphinx-doc.org/)-style
documentation:
```python
def foo(arg):
"""Short description.
:param int arg: Some number.
:returns: Argument
:rtype: int
"""
return arg
```
3. Remember to use `./venv/bin/pylint`.
## Command line usage
The letsencrypt commandline tool has a builtin help:
```
letsencrypt --help
```
## More Information
- Further setup, documentation and open projects are available in the
[Wiki].
- Join us at our IRC channel: #letsencrypt at [Freenode].
- Client software development can be discussed on this [mailing
list]. To subscribe without a Google account, send an email to
client-dev+subscribe@letsencrypt.org.
[augeas]: http://augeas.net
[Freenode]: https://freenode.net
[Let's Encrypt]: https://letsencrypt.org
[m2crypto]: https://github.com/M2Crypto/M2Crypto
[mailing list]: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev
[swig]: http://www.swig.org
[wiki]: https://github.com/letsencrypt/lets-encrypt-preview/wiki

78
README.rst Normal file
View File

@@ -0,0 +1,78 @@
About the Let's Encrypt Client
==============================
In short: getting and installing SSL/TLS certificates made easy (`watch demo video`_).
The Let's Encrypt Client is a tool that talks to the Let's Encrypt CA
so you can comfortably and quickly get trusted TLS certificates that just
work without warnings in every browser.
It's all automated:
* The tool will prove domain control to the CA and submit a CSR (Certificate
Signing Request).
* If domain control has been proven, a certificate will get issued and the tool
will automatically install it.
All you need to do is:
::
user@www:~$ sudo letsencrypt www.example.org
**Encrypt ALL the things!**
.. image:: https://travis-ci.org/letsencrypt/lets-encrypt-preview.svg?branch=master
:target: https://travis-ci.org/letsencrypt/lets-encrypt-preview
.. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU
Disclaimer
----------
This is a **DEVELOPER PREVIEW** intended for developers and testers only.
**DO NOT RUN THIS CODE ON A PRODUCTION SERVER. IT WILL INSTALL CERTIFICATES
SIGNED BY A TEST CA, AND WILL CAUSE CERT WARNINGS FOR USERS.**
Current Features
----------------
* web servers supported:
- apache2.x (tested and working on Ubuntu Linux)
* the private key is generated locally on your system
* can talk to the Let's Encrypt (demo) CA or optionally to other ACME
compliant services
* can get domain-validated (DV) certificates
* can revoke certificates
* adjustable RSA key bitlength (2048 (default), 4096, ...)
* optionally can install a http->https redirect, so your site effectively
runs https only
* fully automated
* configuration changes are logged and can be reverted using the CLI
* text and ncurses UI
* Free and Open Source Software, made with Python.
Links
-----
Documentation: https://letsencrypt.readthedocs.org/
Software project: https://github.com/letsencrypt/lets-encrypt-preview
Main Website: https://letsencrypt.org/
IRC Channel: #letsencrypt on `Freenode`_
Mailing list: `client-dev`_ (to subscribe without a Google account, send an
email to client-dev+subscribe@letsencrypt.org)
.. _Freenode: https://freenode.net
.. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev

8
docs/api.rst Normal file
View File

@@ -0,0 +1,8 @@
=================
API Documentation
=================
.. toctree::
:glob:
api/**

24
docs/index.rst
View File

@@ -1,18 +1,17 @@
.. Let's Encrypt documentation master file, created by
sphinx-quickstart on Sun Nov 23 20:35:21 2014.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Let's Encrypt's documentation!
=========================================
API documentation
-----------------
Welcome to the Let's Encrypt client documentation!
==================================================
.. toctree::
:glob:
:maxdepth: 2
api/**
intro
using
project
.. toctree::
:maxdepth: 1
api
Indices and tables
@@ -21,4 +20,3 @@ Indices and tables
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

6
docs/intro.rst Normal file
View File

@@ -0,0 +1,6 @@
============
Introduction
============
.. include:: ../README.rst
.. include:: ../CHANGES.rst

77
docs/project.rst Normal file
View File

@@ -0,0 +1,77 @@
================================
The Let's Encrypt Client Project
================================
.. _hacking:
Hacking
=======
In order to start hacking, you will first have to create a development
environment:
::
./venv/bin/python setup.py dev
The code base, including your pull requests, **must** have 100% test statement
coverage **and** be compliant with the :ref:`coding-style`.
The following tools are there to help you:
- ``./venv/bin/tox`` starts a full set of tests. Please make sure you
run it before submitting a new pull request.
- ``./venv/bin/tox -e cover`` checks the test coverage only.
- ``./venv/bin/tox -e lint`` checks the style of the whole project,
while ``./venv/bin/pylint --rcfile=.pylintrc file`` will check a single `file` only.
.. _coding-style:
Coding style
============
Please:
1. **Be consistent with the rest of the code**.
2. Read `PEP 8 - Style Guide for Python Code`_.
3. Follow the `Google Python Style Guide`_, with the exception that we
use `Sphinx-style`_ documentation:
::
def foo(arg):
"""Short description.
:param int arg: Some number.
:returns: Argument
:rtype: int
"""
return arg
4. Remember to use ``./venv/bin/pylint``.
.. _Google Python Style Guide: https://google-styleguide.googlecode.com/svn/trunk/pyguide.html
.. _Sphinx-style: http://sphinx-doc.org/
.. _PEP 8 - Style Guide for Python Code: https://www.python.org/dev/peps/pep-0008
Updating the Documentation
==========================
In order to generate the Sphinx documentation, run the following commands.
::
./venv/bin/python setup.py docs
cd docs
make clean html SPHINXBUILD=../venv/bin/sphinx-build
This should generate documentation in the ``docs/_build/html`` directory.

60
docs/using.rst Normal file
View File

@@ -0,0 +1,60 @@
==============================
Using the Let's Encrypt client
==============================
Prerequisites
=============
The demo code is supported and known to work on **Ubuntu only** (even
closely related `Debian is known to fail`_).
Therefore, prerequisites for other platforms listed below are provided
mainly for the :ref:`developers <hacking>` reference.
In general:
* `swig`_ is required for compiling `m2crypto`_
* `augeas`_ is required for the ``python-augeas`` bindings
.. _Debian is known to fail: https://github.com/letsencrypt/lets-encrypt-preview/issues/68
Ubuntu
------
::
sudo apt-get install python python-setuptools python-virtualenv python-dev \
gcc swig dialog libaugeas0 libssl-dev ca-certificates
Mac OSX
-------
::
sudo brew install augeas swig
Installation
============
::
virtualenv --no-site-packages -p python2 venv
./venv/bin/python setup.py install
sudo ./venv/bin/letsencrypt
Usage
=====
The letsencrypt commandline tool has a builtin help:
::
letsencrypt --help
.. _augeas: http://augeas.net/
.. _m2crypto: https://github.com/M2Crypto/M2Crypto
.. _swig: http://www.swig.org/