TLS / HTTPS

Enable TLS / HTTPS support

These settings are for configuring the TLS / HTTPS support for datarhei Core.

Configuration

JSON

{
   "tls": {
      "address": ":8181",
      "enable": false,
      "auto": false,
      "mail": "[e-mail]",
      "cert_file": "",
      "key_file": "",
   }
}

ENV

CORE_TLS_ADDRESS=":8181"
CORE_TLS_ENABLE=false
CORE_TLS_AUTO=false
CORE_TLS_MAIL=[e-mail]
CORE_TLS_CERT_FILE=
CORE_TLS_KEY_FILE=

address (string)

If TLS is enabled, the HTTPS server will listen on this address. The default address is :8181.

The default :8181 will listen on all interfaces on port 8181. To use a specific interface, write additionally it's IP, e.g. 127.0.0.1:8181 to only listen on the loopback interface.

enable (bool)

Set this value to true in order to enable TLS / HTTPS support. If enabled you have to either provide your own certificate (see cert_file and key_file) or enable automatic certificate from Let's Encrypt (see auto).

If TLS is enabled, a HTTP server listening on address will be additionally started. This server provides access to everything as the HTTPS server, additionally it will allow ACME http-1 challenges in case Let's Encrypt (auto) certificates are enabled.

By default this is set to false.

auto (bool)

Enable automatic certificate generation from Let's Encrypt. This only works if enable is set to true and at least one public hostname is defined in host.name. All listed hostnames will be included in the certificate. All listed public hostnames is required to point to the host where datarhei Core is running on.

In order for Let's Encrypt to resolve the http-1 challenge, the HTTP server of the datarhei Core must be reachable on port 80. Either by setting address to :80 or by forwarding/mapping port 80 to the actual port the HTTP server is listening on.

The obtained certificates will be stored in the /cert subdirectory of db.dir to be available after a restart.

Any provided paths in cert_file and key_file will be ignored.

By default this is set to false.

mail (string)

An email address that is required for Let's Encrypt in order to receive a certificate.

By default the email address [e-mail] is used.

cert_file (string)

If you bring your own certificate, provide the path to the certificate file in PEM format.

By default this is not set.

key_file (string)

If you bring your own certificate, provide the path to the key file in PEM format

By default this is not set.

Examples

Let's Encrypt

If you want to use automatic certificates from Let's Encrypt, set tls.enable and tls.auto to true. and host.name has to be set to the domain name this host will be reachable. Otherwise the ACME http-1 challenge will not work.

JSON

{
   "address": ":80",
   "host": {
      "name": ["domain.com"],
      "auto": false
   },
   "tls": {
      "address": ":8181",
      "enable": true,
      "auto": true,
      "mail": "[e-mail]"
   }
}

ENV

CORE_ADDRESS=:80
CORE_HOST_NAME=domain.com
CORE_HOST_AUTO=false
CORE_TLS_ADDRESS=:8181
CORE_TLS_ENABLE=true
CORE_TLS_AUTO=true
CORE_TLS_EMAIL=[e-mail]

Self-Signed certificates

To create a self-signed certificate and key file pair, run this command and provide a reasonable value for the Common Name (CN). The CN is the fully qualified name of the host the instance is running on (e.g., localhost). You can also use an IP address or a wildcard name, e.g., *.example.com.

RSA SSL certificate

openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem -subj '/CN=localhost'

ECDSA SSL certificate

openssl ecparam -name secp521r1 -genkey -out key.pem
openssl req -new -x509 -key key.pem -out cert.pem -days 365 -subj '/CN=localhost'

Call openssl ecparam -list_curves to see all available supported curves listed.

JSON

{
   "host": {
      "name": ["domain.com"],
      "auto": false
   },
   "tls": {
      "address": ":8181",
      "enable": true,
      "auto": false,
      "cert_file": "/core/config/example.cert",
      "key_file": "/core/config/example.key"
   }
}

ENV

CORE_HOST_NAME=domain.com
CORE_HOST_AUTO=false
CORE_TLS_ADDRESS=:8181
CORE_TLS_ENABLE=true
CORE_TLS_AUTO=false
CORE_TLS_CERT_FILE=/core/config/example.cert
CORE_TLS_KEY_FILE=/core/config/example.key