# mod\_ssl\_letsencrypt

Source: https://zotonic.com/docs/1754/mod_ssl_letsencrypt

URI: https://zotonic.com/id/1754

Language: en



Request certificates from Let’s Encrypt.

Let’s Encrypt <<https://www.letsencrypt.com/>> provides free SSL certificates.

Zotonic can request these certificates automatically, easing deployment of https secured web sites.

Hostname & port requirements
----------------------------

There are some criteria that must for each site requesting a certificate.

1. Primary hostname(s) resolve using DNS
2. Resolved DNS address is not a LAN address
3. Site is reachable on the resolved address
4. Listening for the hostname on that address

Zotonic *must* listen on http port 80 and ssl port 443 for connections. If you use any other ports then requesting a certificate will fail.

See [Port configurations](/id/doc_developerguide_configuration_port_ssl_configuration#ref-port-ssl-configuration) for more information about the configuring the correct port numbers and optional proxy settings.

Requesting a certificate
------------------------

In the admin, go to System > Modules and ensure that `mod_ssl_letsencrypt` is enabled.

After mod\_ssl\_letsencrypt is enabled, go to System > SSL Certificates.

In the *Let’s Encrypt* panel you can request a certificate. Check the alternative names you want to include in the certificates. (E.g. *example.com* and \*[www.example.com\*)](<http://www.example.com*)>).

The certificate request will run on the background and the status will be shown in the panel.

After a certificate was received, make sure that Let’s Encrypt is the first module on the SSL Certificates list by disabling all modules above Lets’s Encrypt.

Now go to your site using https, you should be see your site protected by a Let’s Encrypt certificate.

Certificate and key files
-------------------------

The certificate and key files are placed into the site sub-directory of the security directory. The subdirectory will be: `sitename/letsencrypt/`

Where *sitename* must be replaced with the name of your site.

The security directory can be found by inspecting the output of:

```erlang
bin/zotonic config
```

The Zotonic *security* directory can be in one of the following directories:

- The environment variable `ZOTONIC_SECURITY_DIR`
- The `~/.zotonic/security` directory
- The `/etc/zotonic/security` directory (only on Linux)
- The OS specific directory for application data files

The OS specific directories are:

- On Unix: `~/.config/zotonic/security/`
- On macOS: `~/Library/Application Support/zotonic/security/`

The default is the OS specific directory.

If there is a directory `priv/security/letsencrypt` inside your site’s OTP application folder then that directory will be used.

Accepted Events
---------------

This module handles the following notifier callbacks:

- `observe_ssl_options`: Return the certificates of this site using `z_depcache:memo`.
- `observe_tick_24h`: Period tick, used to check for cert upgrade using `gen_server:cast`.

Delegate callbacks:

- `event/2` with `submit` messages: `request_cert`.

License: 

Attribution: 

Related resources: https://zotonic.com/api/agent/related/1754?language=en


## API access

- [API help](<https://zotonic.com/api-help>)
- [OpenAPI specification](<https://zotonic.com/openapi.json>)
- [This resource as JSON](<https://zotonic.com/api/agent/resource/1754?language=en>)
