Install or Replace a Server Certificate

Replace a manually managed Polarity Server certificate and verify that clients receive the intended certificate.

Applies To

Standard Polarity Server v5 Docker installations under /app, with TLS terminated by the bundled web container. Use this workflow for initial installation or renewal of a manually supplied certificate.

Before You Begin

Complete Prepare Certificate and Private Key Files. Have administrative access to the Docker host and a maintenance window. Preserve a valid, matching previous certificate and key pair for recovery, along with the relevant configuration, symlink targets, ownership, permissions, and SELinux labels where applicable.

Check the active configuration before copying files. Copy the prepared files to the following locations on the Polarity Server, preserving the separate web, platform, and CA files.

Do not replace files managed by automatic certificate issuance, including Let's Encrypt, with this manual workflow. If files are symlinks or the active configuration differs from the standard layout, determine the owning certificate mechanism first.

Install the Prepared Files

Record the certificate currently served, its expiry, and the active configuration. Create a protected backup of the current certificate files and configuration before changing them. Preserve symlinks and their targets rather than retaining only a broken reference.

Copy the prepared files to the host destinations below. Keep the key pair consistent across both consumers. Apply the deployment's required ownership and permissions so the relevant container process can read its key without making it broadly readable.

Host Destination	Contents	Consumer
`/app/caddy/config/server.crt`	Server leaf, followed by issuing intermediates	`polarity_web`
`/app/caddy/config/server.key`	Matching unencrypted PKCS#8 private key	`polarity_web`
`/app/certs/polarity.pem`	Server leaf; its CA chain is loaded separately	`polarity_platform`
`/app/certs/polarity_key.pem`	Same matching unencrypted PKCS#8 private key	`polarity_platform`

Use server-fullchain.pem for server.crt, server-leaf.pem for polarity.pem, and server.key for both private-key destinations. Place the CA chain certificates in /app/certs/ca as described in Configure CA Certificate Chains. The two certificate files identify the same server, but the consumers load the rest of the chain differently.

To combine the three example certificate files directly at the web destination after backup and validation, run this command on the server with the required write permission.

cat cert1.crt cert2.crt cert3.crt > /app/caddy/config/server.crt

Here cert1.crt is the server leaf, followed by its intermediate and root CA certificates. A shell redirection writes as the current shell user; use an administrative shell with the required access.

Recheck the installed certificate/key pairs using the commands in the preparation procedure, substituting each installed pair's paths. Confirm that container users can read the required files. Stop if any pair differs or the files are inaccessible.
Restart using the packaged scripts on the Docker host. This interrupts service. Run with the account and privileges used to administer this installation; if shutdown fails, investigate before continuing.
```
cd /app && ./down.sh && ./up.sh
```

Verify the Result

From an authorized client or administrative workstation, replace polarity.example.test with the actual server DNS name. For a private CA, place the approved root certificate in root-ca.pem.

openssl s_client -connect polarity.example.test:443 \
  -servername polarity.example.test \
  -verify_hostname polarity.example.test \
  -verify_return_error -CAfile root-ca.pem -showcerts </dev/null

Require a successful exit and successful certificate verification. For a public CA, use the client's applicable CA bundle rather than the example private root file. OpenSSL trust configuration can differ from browser or desktop client trust.

Inspect the served leaf's identity, issuer, serial number or fingerprint, and expiry against the staged certificate. Open Polarity Web and connect the Polarity Client from a representative workstation. Confirm that each trusts the certificate without a warning and that normal application access works. Review container startup and TLS errors if the UI is unavailable. A successful TLS handshake alone does not establish application health.

Recover From a Failed Replacement

If the server does not start or clients cannot connect, retain diagnostic logs and restore the previous matching certificate/key pair at every destination changed. Restore the corresponding configuration, symlinks, ownership, permissions, and labels from the protected backup. Restart with the packaged scripts, then repeat the client and application checks.