You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

166 lines
5.5 KiB

  1. .. image:: https://img.shields.io/badge/licence-AGPL--3-blue.svg
  2. :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
  3. :alt: License: AGPL-3
  4. =============================================
  5. Request SSL certificates from letsencrypt.org
  6. =============================================
  7. This module was written to have your Odoo installation request SSL certificates
  8. from https://letsencrypt.org automatically.
  9. Installation
  10. ============
  11. After installation, this module generates a private key for your account at
  12. letsencrypt.org automatically in ``$data_dir/letsencrypt/account.key``. If you
  13. want or need to use your own account key, replace the file.
  14. For certificate requests to work, your site needs to be accessible via plain
  15. HTTP, see below for configuration examples in case you force your clients to
  16. the SSL version.
  17. After installation, trigger the cronjob `Update letsencrypt certificates` and
  18. watch your log for messages.
  19. This addon depends on the ``openssl`` binary and the ``acme_tiny`` and ``IPy``
  20. python modules.
  21. For installing the OpenSSL binary you can use your distro package manager.
  22. For Debian and Ubuntu, that would be:
  23. sudo apt-get install openssl
  24. For installing the ACME-Tiny python module, use the PIP package manager:
  25. sudo pip install acme-tiny
  26. For installing the IPy python module, use the PIP package manager:
  27. sudo pip install IPy
  28. Configuration
  29. =============
  30. This addons requests a certificate for the domain named in the configuration
  31. parameter ``web.base.url`` - if this comes back as ``localhost`` or the like,
  32. the module doesn't request anything.
  33. If you want your certificate to contain multiple alternative names, just add
  34. them as configuration parameters ``letsencrypt.altname.N`` with ``N`` starting
  35. from ``0``. The amount of domains that can be added are subject to `rate
  36. limiting <https://community.letsencrypt.org/t/rate-limits-for-lets-encrypt/6769>`_.
  37. Note that all those domains must be publicly reachable on port 80 via HTTP, and
  38. they must have an entry for ``.well-known/acme-challenge`` pointing to your odoo
  39. instance.
  40. Usage
  41. =====
  42. The module sets up a cronjob that requests and renews certificates automatically.
  43. After the first run, you'll find a file called ``domain.crt`` in
  44. ``$datadir/letsencrypt``, configure your SSL proxy to use this file as certificate.
  45. .. image:: https://odoo-community.org/website/image/ir.attachment/5784_f2813bd/datas
  46. :alt: Try me on Runbot
  47. :target: https://runbot.odoo-community.org/runbot/149/8.0
  48. For further information, please visit:
  49. * https://www.odoo.com/forum/help-1
  50. In depth configuration
  51. ======================
  52. This module uses ``openssl`` to generate CSRs suitable to be submitted to
  53. letsencrypt.org. In order to do this, it copies ``/etc/ssl/openssl.cnf`` to a
  54. temporary and adapts it according to its needs (currently, that's just adding a
  55. ``[SAN]`` section if necessary). If you want the module to use another configuration
  56. template, set config parameter ``letsencrypt.openssl.cnf``.
  57. After refreshing the certificate, the module attempts to run the content of
  58. ``letsencrypt.reload_command``, which is by default ``sudo service nginx reload``.
  59. Change this to match your server's configuration.
  60. You'll also need a matching sudo configuration, like::
  61. your_odoo_user ALL = NOPASSWD: /usr/sbin/service nginx reload
  62. Further, if you force users to https, you'll need something like for nginx::
  63. if ($scheme = "http") {
  64. set $redirect_https 1;
  65. }
  66. if ($request_uri ~ ^/.well-known/acme-challenge/) {
  67. set $redirect_https 0;
  68. }
  69. if ($redirect_https) {
  70. rewrite ^ https://$server_name$request_uri? permanent;
  71. }
  72. and this for apache::
  73. RewriteEngine On
  74. RewriteCond %{HTTPS} !=on
  75. RewriteCond %{REQUEST_URI} "!^/.well-known/"
  76. RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]
  77. In case you need to redirect other nginx sites to your Odoo instance, declare
  78. an upstream for your odoo instance and do something like::
  79. location /.well-known {
  80. proxy_pass http://yourodooupstream;
  81. }
  82. If you're using a multi-database installation (with or without dbfilter option)
  83. where /web/databse/selector returns a list of more than one database, then
  84. you need to add ``letsencrypt`` addon to wide load addons list
  85. (by default, only ``web`` addon), setting ``--load`` option.
  86. For example, ``--load=web,letsencrypt``
  87. Bug Tracker
  88. ===========
  89. Bugs are tracked on `GitHub Issues <https://github.com/OCA/server-tools/issues>`_.
  90. In case of trouble, please check there if your issue has already been reported.
  91. If you spotted it first, help us smashing it by providing a detailed and welcomed feedback
  92. `here <https://github.com/OCA/server-tools/issues/new?body=module:%20letsencrypt%0Aversion:%209.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
  93. Credits
  94. =======
  95. Contributors
  96. ------------
  97. * Holger Brunn <hbrunn@therp.nl>
  98. * Antonio Espinosa <antonio.espinosa@tecnativa.com>
  99. * Dave Lasley <dave@laslabs.com>
  100. ACME implementation
  101. -------------------
  102. * https://github.com/diafygi/acme-tiny/blob/master/acme_tiny.py
  103. Icon
  104. ----
  105. * https://helloworld.letsencrypt.org
  106. Maintainer
  107. ----------
  108. .. image:: https://odoo-community.org/logo.png
  109. :alt: Odoo Community Association
  110. :target: https://odoo-community.org
  111. This module is maintained by the OCA.
  112. OCA, or the Odoo Community Association, is a nonprofit organization whose
  113. mission is to support the collaborative development of Odoo features and
  114. promote its widespread use.
  115. To contribute to this module, please visit https://odoo-community.org.