Configure TLS certificates for BRIX AI

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: Self-signed certificates are generated automatically. This mode is used by default and is suitable for testing.
• Custom: Uses certificates issued by a public or private Certificate Authority (CA), or self-signed certificates.
• 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:

1. • 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

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