site_encrypt v0.2.1 SiteEncrypt behaviour View Source
Link to this section Summary
Functions
Invoke this macro from certification/0
to return the fully shaped configuration.
Force renews the certificate for the given site.
Returns the paths to the certificates and the key for the given site.
Callbacks
Invoked during startup to obtain certification info.
Invoked after the new certificate has been obtained.
Link to this section Types
Specs
certification()
Specs
id() :: any()
Uniquely identifies the site certified via site_encrypt.
The actual value is determined by the adapter used to start the site. For example, if
SiteEncrypt.Phoenix
is used, the site id is the endpoint module.
Link to this section Functions
Invoke this macro from certification/0
to return the fully shaped configuration.
The minimal implementation of certification/0
looks as follows:
@impl SiteEncrypt
def certification do
SiteEncrypt.configure(
client: :native,
domains: ["mysite.com", "www.mysite.com"],
emails: ["contact@abc.org", "another_contact@abc.org"],
db_folder: Application.app_dir(:phoenix_demo, Path.join(~w/priv site_encrypt/))
# set OS env var MODE to "staging" or "production" on staging/production hosts
directory_url:
case System.get_env("MODE", "local") do
"local" -> {:internal, port: 4002}
"staging" -> "https://acme-staging-v02.api.letsencrypt.org/directory"
"production" -> "https://acme-v02.api.letsencrypt.org/directory"
end
)
end
Options
:client
- Required. Can be either:native
or:certbot
.The native client requires no extra OS-level dependencies, and it runs faster, which is especially useful in a local development and tests. However, this client is very immature, possibly buggy, and incomplete.
The certbot client is a wrapper around the certbot tool, which has to be installed on the host machine. This client is much more reliable than the native client, but it is also significantly slower.
As a compromise between these two choices, you can consider running certbot client in production and during CI tests, while using the native client for local development and local tests.
:domains
- Required. The list of domains for which the certificate will be obtained. Must contain at least one element.:emails
- Required. The list of email addresses which will be passed to the CA when creating the new account.:db_folder
- Required. The folder where site_encrypt stores its data, such as certificates and account keys.:directory_url
- Required. The URL to CA directory resource. It can be either a string (e.g."https://acme-v02.api.letsencrypt.org/directory"
) or a tuple in the shape of{:internal, port: local_acme_server_port}
. In the latter case, an internal ACME server will be started at the given port. This is useful for local development and testing.:backup
- Path to the backup file. If this option is provided, site_encrypt will backup the entire content of the:db_folder
to the given path after every successful certification. When the system is being started, if the backup file exists while the:db_folder
is empty, the system will perform a restore. The generated file will be a zipped tarball. If this option is not provided no backup will be generated.:days_to_renew
- A positive integer which determines the next renewal attempt. For example, if this value is 30, the certificate will be renewed if it expires in 30 days or less. The default value is30
.:log_level
- Logger level for info messages. The default value is:info
.
Specs
force_renew(id()) :: :ok
Force renews the certificate for the given site.
Be very careful when invoking this function in production, because you might trip some rate limit at the CA server (see here for Let's Encrypt limits).
Specs
Returns the paths to the certificates and the key for the given site.
Link to this section Callbacks
Specs
certification() :: certification()
Invoked during startup to obtain certification info.
See configure/1
for details.
Specs
handle_new_cert() :: any()
Invoked after the new certificate has been obtained.