Help Center

Root certificate: how to make Pyrus trust your internal certificate authority

Cloudless Pyrus

If the servers that Pyrus connects to over HTTPS (bots, mail servers, SSO, S3 storage) use certificates issued by your internal certificate authority (CA), Pyrus must trust this certificate authority. Otherwise, it won't be able to connect to these servers: requests will fail with a certificate verification error.

The certificate is added to the Pyrus Datacenter settings, so it is preserved when you update Pyrus.

Prepare the certificate

You need the root certificate of the certificate authority in PEM format. This is a text file that begins with the line -----BEGIN CERTIFICATE-----.

Note: an intermediate certificate alone is not enough; the file must contain the root certificate.

If the chain includes intermediate certificate authorities, add their certificates to the same file after the root one:

cat root-ca.crt issuing-ca.crt > corp-root-ca.crt

If the certificate is in binary DER format (a .cer file without a text header), convert it:

openssl x509 -inform der -in corp-root-ca.cer -out corp-root-ca.crt

Installing with Docker Compose

Run all commands on the Pyrus server in the folder that contains docker-compose.yml.

  1. Put the certificate in the certs folder and allow all users to read it: Pyrus services run without administrator privileges.

    mkdir -p certs
cp corp-root-ca.crt certs/corp-root-ca.crt
chmod 644 certs/corp-root-ca.crt

  2. Next to docker-compose.yml, create the docker-compose.override.yml file:

    x-corp-ca: &corp-ca
  volumes:
    - ./certs/corp-root-ca.crt:/etc/ssl/certs/corp-root-ca.pem:ro

services:
  web-api: *corp-ca
  async-worker: *corp-ca
  files: *corp-ca
  identity-server: *corp-ca
  bind: *corp-ca
  mail-reader: *corp-ca
  mail-sender: *corp-ca
  notification-service: *corp-ca
  pyrus-schedule-to-today: *corp-ca
  preview: *corp-ca
  pyrus-setup: *corp-ca
  elastic-console: *corp-ca
  familiar: *corp-ca
  stt-service: *corp-ca
  goskey: *corp-ca

    On servers with SELinux enabled (RHEL, CentOS, Rocky Linux), replace :ro with :ro,z in the line under volumes.

    Docker Compose applies this file automatically. When you update Pyrus, you replace only docker-compose.yml, so the setting is preserved.

    Note: docker-compose.override.yml must list only the services that exist in your docker-compose.yml. Otherwise, Docker Compose won't start and will show the error service "..." has neither an image nor a build context specified.

    To see the list of services, run:

    docker compose --profile all config --services

  3. Recreate the containers:

    docker compose up -d

  4. Make sure the certificate is visible inside the container:

    docker exec pyrus-web-api head -1 /etc/ssl/certs/corp-root-ca.pem

    The command should output -----BEGIN CERTIFICATE-----.

Tip: if you run Docker Compose with an explicitly specified file (docker compose -f docker-compose.yml ...), docker-compose.override.yml won't be applied. Specify it explicitly: docker compose -f docker-compose.yml -f docker-compose.override.yml up -d.

Installing in Kubernetes

You need the pyrus-datacenter Helm chart version 2.0.40 or later. The current version is shown in the CHART column of the output of this command:

helm -n pyrus list

In the examples below, the namespace is pyrus and the release name is pyrus-datacenter. If yours are different, use your own values.

  1. Add the certificate to the values file that you pass with every helm upgrade. The chart will create a Secret and attach the file to Pyrus services:

    defaults:
  secretRef:
    "/etc/ssl/certs":
      corp-root-ca.pem: |
        -----BEGIN CERTIFICATE-----
        ...contents of corp-root-ca.crt...
        -----END CERTIFICATE-----

    All lines of the certificate must have the same indentation. If the file already has a defaults section, add secretRef to it.

    Note: don't name the file ca-certificates.crt: this would replace the entire system certificate bundle.

  2. Apply the changes with your usual update command. Specify the current chart version so that the chart itself isn't updated along with the settings:

    helm -n pyrus upgrade pyrus-datacenter pyrus-datacenter-k8s/pyrus-datacenter \
  -f pyrus.values.yaml \
  --version <current chart version> \
  --reset-values

  3. Make sure the certificate is visible inside the pod:

    kubectl -n pyrus exec deploy/pyrus-web-api -- head -1 /etc/ssl/certs/corp-root-ca.pem

    The command should output -----BEGIN CERTIFICATE-----.

Note: when updating with the --reset-values flag, always pass the values file with the certificate. Without it, the chart will remove the certificate, and Pyrus will stop trusting your certificate authority again.

Was this article helpful?