SiteEncrypt behaviour (site_encrypt v0.4.2) View Source
Functions for interacting with sites managed by SiteEncrypt.
Link to this section Summary
Functions
Invoke this macro from certification/0
to return the fully shaped configuration.
Generates a new throwaway certificate for the given site.
Unconditionally obtains the new certificate for the site.
Returns the paths to the certificates and the key for the given site.
Sets the new site certificate.
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.
Specs
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"],
# By default the certs will be stored in tmp/site_encrypt_db, which is convenient for
# local development. Make sure that tmp folder is gitignored.
#
# Set OS env var SITE_ENCRYPT_DB on staging/production hosts to some absolute path
# outside of the deployment folder. Otherwise, the deploy may delete the db_folder,
# which will effectively remove the generated key and certificate files.
db_folder:
System.get_env("SITE_ENCRYPT_DB", Path.join("tmp", "site_encrypt_db")),
# set OS env var CERT_MODE to "staging" or "production" on staging/production hosts
directory_url:
case System.get_env("CERT_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
.:key_size
- The size used for generating private keys. The default value is4096
.:mode
- When set to:auto
, the certificate will be automatically created or renewed when needed.
When set to :manual
, you need to start the certification manually, using functions such as
SiteEncrypt.force_certify/1
or SiteEncrypt.dry_certify/2
. This can be useful for the
first deploy, where you want to manually test the certification. In :test
mix environment
the mode is always :manual
. The default value is :auto
.
Specs
Generates a new throwaway certificate for the given site.
This function will perform the full certification at the given CA server. The new certificate won't be used by the site, nor stored on disk. This is mostly useful to test the certification through the staging CA server from the production server, which can be done as follows:
SiteEncrypt.dry_certify(
MySystemWeb.Endpoint,
directory_url: "https://acme-staging-v02.api.letsencrypt.org/directory"
)
If for some reasons you want to apply the certificate to the site, you can pass the returned
pems to set_certificate/2
.
Specs
force_certify(id()) :: :ok | :error
Unconditionally obtains the new certificate for the 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.
Specs
Sets the new site certificate.
This operation doesn't persist the certificate in the client storage. As a result, if the client previously obtained and stored a valid certificate, that certificate will be used after the endpoint is restarted.
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.