# TLS / HTTPS

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

## Configuration

{% tabs %}
{% tab title="JSON" %}

```
{
   "tls": {
      "address": ":8181",
      "enable": false,
      "auto": false,
      "mail": "cert@datarhei.com",
      "cert_file": "",
      "key_file": "",
   }
}
```

{% endtab %}

{% tab title="ENV" %}

```
CORE_TLS_ADDRESS=":8181"
CORE_TLS_ENABLE=false
CORE_TLS_AUTO=false
CORE_TLS_MAIL=cert@datarhei.com
CORE_TLS_CERT_FILE=
CORE_TLS_KEY_FILE=
```

{% endtab %}
{% endtabs %}

### address (string)

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

{% hint style="info" %}
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.
{% endhint %}

### 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](#cert_file) and [key\_file](#key_file)) or enable automatic certificate from Let's Encrypt (see [auto](#auto)).

If TLS is enabled, a HTTP server listening on [address](/core/configuration.md#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](/core/configuration/hostname.md#name-array). 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.

{% hint style="warning" %}
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](/core/configuration.md#address) to `:80` or by forwarding/mapping port 80 to the actual port the HTTP server is listening on.
{% endhint %}

The obtained certificates will be stored in the `/cert` subdirectory of [db.dir](/core/configuration/database.md#dir-string) 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 `cert@datarhei.com` 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](#enable-bool) and [tls.auto](#auto-bool) to `true`. and [host.name](/core/configuration/hostname.md#name-array) has to be set to the domain name this host will be reachable. Otherwise the ACME http-1 challenge will not work. 

{% tabs %}
{% tab title="JSON" %}

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

{% endtab %}

{% tab title="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=cert@domain.com
```

{% endtab %}
{% endtabs %}

### 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.

{% tabs %}
{% tab title="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"
   }
}
```

{% endtab %}

{% tab title="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
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.datarhei.com/core/configuration/tls-https.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.