|
<< Click to Display Table of Contents >> Raynet One > 2026.4 > 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 exclusively as non-root users (rootless containers). Root containers are no longer supported. 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.
For containers that do not invoke update-ca-certificates at startup — such as the standalone Linux runner — certificate trust can be configured through OpenSSL environment variables instead. This approach mounts the certificate directory as a read-only volume and directs OpenSSL to it via the SSL_CERT_FILE or SSL_CERT_DIR environment variable. No modifications to the container entrypoint are required.
Use SSL_CERT_FILE to point OpenSSL to a single PEM file that contains one or more trusted CA certificates. Use SSL_CERT_DIR to point OpenSSL to a directory of individual certificate files. SSL_CERT_FILE is the simpler choice when all trusted CAs are bundled in a single file.
The following example extends the basic Linux runner Docker Compose configuration to trust a custom CA. Place your CA certificate file as certs/rootCA.crt in the same directory as the Compose file, then add the volume mount and environment variable shown below to the service definition:
services:
rno-runner:
volumes:
- rno_runner_data:/app/data
- ./certs:/certs:ro
environment:
SSL_CERT_FILE: /certs/rootCA.crt
To trust multiple CA certificates stored as separate files, use SSL_CERT_DIR instead:
SSL_CERT_DIR: /certs
Note: These environment variables are recognized by OpenSSL on Linux and are therefore effective for all .NET services running on Linux containers, including Raynet One services and the Linux runner. The variable takes effect at process startup; no entrypoint customization or container rebuild is needed.
The standalone Linux runner container requires two Linux kernel capabilities to perform network discovery and inventory operations. These capabilities must be explicitly granted in the Docker Compose configuration because rootless containers do not inherit elevated kernel privileges.
•NET_RAW – Required for sending raw ICMP packets (ping) used during network discovery and inventory scans. Without this capability, network-based discovery operations will fail.
•NET_BIND_SERVICE – Required to bind to port 591 (the RVIA Data Service port). Under a rootless container, binding to ports below 1024 is restricted without this capability.
Add the following entries to the runner service definition in your Docker Compose file to grant these capabilities:
cap_add:
- NET_RAW
- NET_BIND_SERVICE
Additionally, the following sysctls entries are required to permit the rootless runner process to use ICMP and to bind to port 591:
sysctls:
net.ipv4.ping_group_range: "0 2147483647"
net.ipv4.ip_unprivileged_port_start: 591
Note: If the runner is not configured to run network discovery or inventory operations, the NET_RAW capability and the net.ipv4.ping_group_range sysctl are not required. However, omitting NET_BIND_SERVICE will prevent the RVIA Data Service from binding to port 591.
Follow the steps below to migrate your custom certificate installation from the previous root-container approach to the rootless container approach using the volume-mount method.
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.