# Let’s Encrypt

This module was written to have your Odoo installation request SSL certificates from https://letsencrypt.org automatically.

Table of contents

- Installation
- Configuration
- Usage
  - In depth configuration
- Bug Tracker
- Credits
  - Authors
  - Contributors
  - Other credits
  - ACME implementation
  - Icon
  - Maintainers

# Installation

After installation, this module generates a private key for your account at letsencrypt.org automatically in `$data_dir/letsencrypt/account.key`. If you want or need to use your own account key, replace the file.

For certificate requests to work, your site needs to be accessible via plain HTTP, see below for configuration examples in case you force your clients to the SSL version.

After installation, trigger the cronjob Update letsencrypt certificates and watch your log for messages.

# Configuration

This addons requests a certificate for the domain named in the configuration parameter `web.base.url` - if this comes back as `localhost` or the like, the module doesn’t request anything.

Futher self-explanatory settings are in Settings -> General Settings. There you can add further domains to the CSR, add a custom script that updates your DNS and add a script that will be used to reload your web server (if needed). The number of domains that can be added to a certificate is capped at 100. A wildcard certificate can be used to avoid that limit.

Note that all those domains must be publicly reachable on port 80 via HTTP, and they must have an entry for `.well-known/acme-challenge` pointing to `$datadir/letsencrypt/acme-challenge` of your odoo instance.

Since DNS changes can take some time to propagate, when we respond to a DNS challenge and the server tries to check our response, it might fail (and probably will). The solution to this is documented in https://tools.ietf.org/html/rfc8555#section-8.2 and basically is a `Retry-After` header under which we can instruct the server to retry the challenge. At the time these lines were written, Boulder had not implemented this functionality. This prompted us to use `letsencrypt.backoff` configuration parameter, which is the amount of minutes this module will try poll the server to retry validating the answer to our challenge, specifically it is the `deadline` parameter of `poll_and_finalize`.

# Usage

The module sets up a cronjob that requests and renews certificates automatically.

Certificates are renewed a month before they expire. Renewal is then attempted every day until it succeeds.

After the first run, you’ll find a file called `domain.crt` in `$datadir/letsencrypt`, configure your SSL proxy to use this file as certificate.

## In depth configuration

If you want to use multiple domains on your CSR then you have to configure them from Settings -> General Settings. If you use a wildcard in any of those domains then letsencrypt will return a DNS challenge. In order for that challenge to be answered you will need to either provide a script (as seen in General Settings) or install a module that provides support for your DNS provider. In that module you will need to create a function in the letsencrypt model with the name `_respond_challenge_dns_$DNS_PROVIDER` where `$DNS_PROVIDER` is the name of your provider and can be any string with length greater than zero, and add the name of your DNS provider in the settings dns_provider selection field.

In any case if a script path is inserted in the settings page, it will be run in case you want to update multiple DNS servers.

A reload command can be set in the Settings as well in case you need to reload your web server. This by default is `sudo /usr/sbin/service nginx reload`

You’ll also need a matching sudo configuration, like:

    your_odoo_user ALL = NOPASSWD: /usr/sbin/service nginx reload

Further, if you force users to https, you’ll need something like for nginx:

    if ($scheme = "http") {
        set $redirect_https 1;
    }
    if ($request_uri ~ ^/.well-known/acme-challenge/) {
        set $redirect_https 0;
    }
    if ($redirect_https) {
        rewrite ^   https://$server_name$request_uri? permanent;
    }

and this for apache:

    RewriteEngine On
    RewriteCond %{HTTPS} !=on
    RewriteCond %{REQUEST_URI} "!^/.well-known/"
    RewriteRule ^/?(.*) https://%{SERVER_NAME}/$1 [R,L]

In case you need to redirect other nginx sites to your Odoo instance, declare an upstream for your odoo instance and do something like:

    location /.well-known {
        proxy_pass    http://yourodooupstream;
    }

If you’re using a multi-database installation (with or without dbfilter option) where /web/databse/selector returns a list of more than one database, then you need to add `letsencrypt` addon to wide load addons list (by default, only `web` addon), setting `--load` option. For example, `--load=web,letsencrypt`

# Bug Tracker

Bugs are tracked on GitHub Issues. In case of trouble, please check there if your issue has already been reported. If you spotted it first, help us to smash it by providing a detailed and welcomed feedback.

Do not contact contributors directly about support or help with technical issues.

# Credits

## Authors

- Therp BV
- Tecnativa
- Acysos S.L

## Contributors

- Holger Brunn <mail@hunki-enterprises.nl>
- Antonio Espinosa <antonio.espinosa@tecnativa.com>
- Dave Lasley <dave@laslabs.com>
- Ronald Portier <ronald@therp.nl>
- Ignacio Ibeas <ignacio@acysos.com>
- George Daramouskas <gdaramouskas@therp.nl>
- Jan Verbeek <jverbeek@therp.nl>

## Other credits

## ACME implementation

- https://github.com/certbot/certbot/tree/0.22.x/acme

## Icon

- https://helloworld.letsencrypt.org

## Maintainers

This module is maintained by the OCA.

OCA, or the Odoo Community Association, is a nonprofit organization whose mission is to support the collaborative development of Odoo features and promote its widespread use.

Current maintainer:

This module is part of the OCA/server-tools project on GitHub.

You are welcome to contribute. To learn how please visit https://odoo-community.org/page/Contribute.