MongoDB TLS Connection Configuration
This guide describes how to configure HAP to trust the CA certificate for the MongoDB server and establish an encrypted TLS connection.
HAP currently supports one-way TLS authentication for MongoDB. mTLS (mutual TLS authentication) is not currently supported.
Before configuring the connection, ensure that TLS is enabled on MongoDB.
Prepare Certificates
Prepare the CA certificate that issued the MongoDB server certificate in PEM format:
| File | Description |
|---|---|
custom-ca.crt | CA certificate used to verify the MongoDB server certificate |
Multiple CA certificates can be placed sequentially in the same custom-ca.crt file.
- The file must contain only public CA certificates, not private keys. A file containing a private key will be rejected in its entirety.
- The MongoDB connection address must match a domain name or IP address in the server certificate.
Mount Certificates
HAP supports importing custom CA certificates starting with v7.4.0.
Mount the CA certificate inside the container. It will be imported automatically when the container starts.
- HAP Standalone Mode (Docker Compose)
- HAP Cluster Mode (Kubernetes)
-
On the HAP server, place the CA certificate in
/data/mingdao/script/volume/cafile/custom-ca.crt. -
Check the
volumesconfiguration of theappservice in/data/mingdao/script/docker-compose.yamland mount the certificate in the container. For example:services:app:volumes:- ./volume/cafile/custom-ca.crt:/Housekeeper/cafile/custom-ca.crt:ro
If the corresponding mount already exists, do not add it again.
Follow Mount Configuration Files to mount the CA certificate at the following path inside the container:
/Housekeeper/cafile/custom-ca.crt
Configure the Connection
Modify the configuration file for your deployment mode:
- HAP Standalone Mode (Docker Compose)
- HAP Cluster Mode (Kubernetes)
Configure the app service in /data/mingdao/script/docker-compose.yaml.
Configure the microservices in config.yaml.
Add tls=true to ENV_MONGODB_OPTIONS, retain any existing parameters, and update the MongoDB addresses, ports, and account details as needed:
ENV_MONGODB_URI: 'mongodb://hap:YOUR_PASSWORD@192.0.2.10:27017,192.0.2.11:27017,192.0.2.12:27017'
ENV_MONGODB_OPTIONS: '?tls=true'
ENV_MONGODB_OPTIONS starts with ?; separate multiple parameters with &.
After configuring, run the following command from the installation manager directory in standalone mode to recreate the app container and apply the Compose configuration:
docker compose -f docker-compose.yaml up -d --no-deps --force-recreate app
Then restart the HAP microservices. In cluster mode, apply the configuration and restart the HAP microservices.