site_encrypt v0.2.0 SiteEncrypt behaviour View Source

Link to this section Summary

Types

Uniquely identifies the site certified via site_encrypt.

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

Link to this opaque

certification()

View Source (opaque)

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

Link to this macro

configure(opts)

View Source (macro)

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 is 30.

  • :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

https_keys(id()) :: [
  keyfile: Path.t(),
  certfile: Path.t(),
  cacertfile: Path.t()
]

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.