# Configure TLS certificates for BRIX AI

> [HTML Version](cortex-tls-settings.html)

Configure TLS certificate settings before installation. They provide secure access to **BRIX AI** via HTTPS in a browser and allow system components, such as AI agents, to download files.

Three certificate management modes are supported:

- [Internal](#internal): Self-signed certificates are generated automatically. This mode is used by default and is suitable for testing.

- [Custom](#custom): Uses certificates issued by a public or private Certificate Authority (CA), or self-signed certificates.

- [ACME](#acme): Uses certificates issued automatically via the ACME protocol using the Let’s Encrypt Certificate Authority.

The Caddy server is used to manage certificates.

## Internal mode

To let the Caddy server automatically generate and manage self-signed certificates:

1. In the `.env` file, uncomment the line with the `TLS\_MODE` parameter and make sure it is set to `internal`.

2. The parameters will be applied automatically when installing **BRIX AI**.

If you update the settings after completing the installation, run the following command to apply the new parameters:

````
./install.sh

3. ````
Export the Caddy root certificate:

````
chmod +x manage-certs.sh  
./manage-certs.sh export-caddy-ca

4. ````
Install the exported `caddy\_root.crt` certificate on client machines as a trusted certificate. The required steps depend on your operating system.

## Custom mode

In this mode, you can use your own TLS certificate:

- From a public CA.

- From a private corporate CA.

- Self-signed.

### Certificate requirements for Custom mode

Certificates in **BRIX AI** must meet the following requirements:

- Format: PEM (base64 encoded).

- Key: RSA or ECDSA, unencrypted.

- Chain: If you use intermediate certificates, append them to the server certificate file.

- SAN (Subject Alternative Names) extension: Enter the hostname in the field specifying additional domains covered by the certificate. Use the value set in the `ELMA\_CORTEX\_HOSTNAME` variable in the `.env` file.

## Enable Custom mode

1. Prepare the certificate files:

	- **server.crt**: Server certificate. If an intermediate certificate chain is used, combine it with the main certificate in this file.

	- **server.key**: Unencrypted private key.

	- **ca.crt**: CA certificate. This file is required only if you use a private corporate CA.

Create a self-signed certificate

  
You can issue a self-signed certificate, for example, for testing purposes, using the following command:

````
./manage-certs.sh generate-self-signed

````
  
You can also generate a certificate manually using the following commands with the **BRIX AI** hostname:

````
source .env  
  
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \\  
  -keyout certs/server.key \\  
  -out certs/server.crt \\  
  -subj "/CN=\$\{ELMA\_CORTEX\_HOSTNAME\}" \\  
  -addext "subjectAltName=DNS:\$\{ELMA\_CORTEX\_HOSTNAME\}"
````

2. ````
Create a folder for certificate files:

````
./manage-certs.sh init

3. ````
Copy the files to the folder:

````
cp /path/to/your/certificate.crt certs/server.crt  
cp /path/to/your/private.key certs/server.key

````
If you use a private CA, also copy its certificate:

````
cp /path/to/your/ca.crt certs/ca.crt

4. ````
In the **.env** environment file, uncomment and set the following parameters:

````
TLS\_MODE=custom  
TLS\_CERT\_PATH=./certs/server.crt  
TLS\_KEY\_PATH=./certs/server.key

5. ````
If you use a CA certificate, specify the path to it so that **BRIX AI** services can communicate over HTTPS:

````
TLS\_CA\_PATH=./certs/ca.crt

````
The CA certificate is passed to services as a Docker secret (`caddy\_root\_ca`), which is added to the system trust store.

6. The parameters will be applied automatically during **BRIX AI** installation. If installation is complete, run the following command to apply new parameters:

````
./install.sh

### ````
Renew TLS certificates

If your certificate expires or needs to be replaced, renew it in one of the following ways:

- Run the script using the command below, specifying the path to the new file.

````
./manage-certs.sh update /path/to/new/cert.crt /path/to/new/key.key

- ````
Run the commands sequentially, inserting the path to the new file.

````
cp /path/to/new/cert.crt certs/server.crt  
cp /path/to/new/key.key certs/server.key  
./install.sh

## ````
ACME mode (Let’s Encrypt)

In this mode, the Caddy server automatically obtains certificates from Let’s Encrypt and renews them.

### Requirements for using ACME mode

Make sure the following conditions are met:

- A DNS record pointing to the IP address of the **BRIX AI** server is configured for the domain name specified in the `ELMA\_CORTEX\_HOSTNAME` variable.

- Ports 80 and 443 are accessible from the internet on the server.

- A valid email address exists for Let’s Encrypt notifications.

````
Enable ACME mode

1. ````
In the `.env` environment file, set the mode to **ACME** and specify an email address for notifications:

````
TLS\_MODE=acme  
ACME\_EMAIL=admin@your-domain.com

2. ````
The parameters will be applied automatically during **BRIX AI** installation. If installation is complete, run the following command to apply new parameters:

````
./install.sh

````
After this, the Caddy server will:

- Obtain certificates from Let’s Encrypt.

- Redirect requests from HTTP to the secure HTTPS protocol.

- Automatically renew the certificate before it expires.

### Troubleshoot ACME

If certificate issuance fails, use verification commands, specifying your **BRIX AI** server address:

1. Check DNS resolution:

````
nslookup \$\{ELMA\_CORTEX\_HOSTNAME\}

2. ````
Check port availability:

````
curl -v http://\$\{ELMA\_CORTEX\_HOSTNAME\}/.well-known/acme-challenge/test

3. ````
Check Caddy server logs:

````
docker service logs elma-cortex\_caddy

## ````
Verify TLS settings

To verify settings before deploying **BRIX AI**, run the following command:

````
./manage-certs.sh check

````
To view current configuration:

````
./manage-certs.sh info

## ````
Troubleshoot certificates

Below are common errors and ways to resolve them.

### Certificate not working after update

Restart the Caddy service to update certificates:

````
docker service update --force elma-cortex\_caddy

### ````
“Certificate file not found” error

Make sure the certificate paths are correct and the files exist by running the following command:

````
./manage-certs.sh check

### ````
SSL verification error for internal services

Check settings:

- For **Internal** mode: Make sure the Caddy root certificate is installed on machines running **BRIX AI**.

- For **Custom** mode with a private CA: Make sure the `TLS\_CA\_PATH` variable in the `.env` file specifies a valid path to the CA certificate.

After correcting the settings, apply them using the following command:

````
./install.sh
````