|
<< Click to Display Table of Contents >> Raynet One > 2026.2 > Installation and Operations Guide > Raynet One On-Premises Installation and Operations Guide > Certificate Management Migrating Certificate Installation to Rootless Containers |
Starting with this release, all Raynet One containers run as non-root users (rootless containers). This is a security hardening measure that limits the attack surface within each container.
This change affects how custom CA certificates and additional trust anchors are installed. If you previously installed certificates by executing commands directly inside a running container as root, you must switch to the volume-mount approach described in this guide.
In previous releases, containers ran as the root user. This allowed administrators to install custom certificates at runtime by attaching to a container and running certificate management commands directly inside it.
Rootless containers run under a dedicated, unprivileged service account. As a result, write access to system certificate directories inside the container is no longer available at runtime. Certificates must instead be provided through Docker volume mounts before containers start. The container startup process reads the mounted certificate files and installs them into the trust store automatically.
In earlier versions, a common method for adding custom CA certificates was to attach to a running container and execute certificate installation commands interactively. This relied on root-level access to write files into the system certificate store and run the update utility.
This approach is no longer supported. Rootless containers do not permit write access to the system certificate directories at runtime. Any certificates installed by this method in previous deployments will not persist and will not be recognized after upgrading to rootless containers.
The supported method for providing custom certificates is to mount the certificate files as read-only volumes into each container that requires them. The container startup process detects the mounted certificates and installs them into the system trust store before the main service starts.
This approach is declarative, reproducible, and consistent with the overall Docker Compose deployment model used by Raynet One. For an overview of the full certificate configuration options, refer to the Certificate Management section.
Follow the steps below to migrate your custom certificate installation from the previous root-container approach to the rootless container approach.
Obtain the certificate files that were previously installed inside the containers. These are typically your organization's root CA certificate and any intermediate CA certificates in PEM format. If you no longer have the original files, request them from your PKI or Security team.
The following certificate files are expected by the deployment:
•certs/rootCA.crt – Root CA certificate in PEM format (used by Linux-based services)
•certs/rootCA.pem – Root CA certificate in PEM format (used by Java-based services such as Keycloak)
Note: Certificate creation and signing are outside the scope of this guide. Contact your PKI or Security team to obtain the required files.
In your deployment directory (the folder containing compose.yml), create a certs/ subdirectory and place your certificate files there:
•certs/rootCA.crt
•certs/rootCA.pem
Important: Restrict the file permissions on the certs/ directory so that certificate files are not readable by unprivileged system users. Private key files must be protected at the file system level.
Enable certificate volume mounts for the relevant services in your compose.yml file. If your deployment provides a compose.certs.yml override file, apply the certificate configuration there instead of editing compose.yml directly. This keeps the base configuration clean and separates certificate-specific settings.
To activate the certificate mounts, locate the commented-out volume entries in compose.yml and remove the comment markers (#) from the following lines for each service that must trust your CA:
•Lines beginning with # - ./certs/rootCA.crt
•Lines beginning with # - ./certs/rootCA.pem
Important: Enable the certificate volume mounts for all services that communicate over HTTPS with other internal services or with external endpoints that use a certificate issued by your private CA. In particular, Keycloak must trust the certificate presented by the frontend during authentication flows. If intermediate certificates are missing from the chain, Keycloak will be unable to generate tokens.
After updating the compose configuration and placing the certificate files, restart the affected services so that the containers start with the volume mounts applied. The startup process will detect the mounted certificates and install them into the container's system trust store automatically.
Apply the updated configuration and restart all services:
docker compose up -d
To verify that the containers started successfully, check the logs for each affected service:
docker compose logs -f backend
docker compose logs -f server-scheduler
After restarting the services, confirm that the certificates are trusted correctly by verifying the following:
•Log in to the Raynet One web interface successfully via HTTPS.
•Confirm that no certificate trust errors appear in the service logs after startup.
•Confirm that Keycloak-based authentication completes without TLS handshake errors in the backend log.
•If your deployment includes outbound HTTPS connections to external services (for example, LDAP over SSL, SMTP, or external APIs), verify that those connections complete successfully.
If a service reports certificate errors after the migration, check the following:
•Verify that the certificate files exist in the certs/ directory and that their file names match the paths configured in the volume mount definitions.
•Confirm that the volume mount entries in compose.yml (or compose.certs.yml) are uncommented and syntactically correct.
•Verify that the CA certificate files are in PEM format. Files in DER format must be converted before use.
•For Java-based services (for example, Keycloak), confirm that rootCA.pem contains the complete certificate chain, including all intermediate certificates.
•Confirm that the volume mounts are enabled for every service that participates in TLS-secured communication, not only the service that reports the error.
Keycloak validates the TLS certificate presented by the frontend during authentication. If the certificate chain is incomplete or if Keycloak does not have the rootCA.pem file mounted and trusted, the TLS handshake will fail and users will be unable to log in.
Ensure that the Keycloak service has the rootCA.pem volume mount active and that the file contains the full certificate chain from the leaf certificate up to the root.