Knowledge Base

Overview

By the end of this article your issued server certificate will be installed on the Traefik host and bound to a hostname, so Traefik presents it for HTTPS connections to that name. The article explains how Traefik loads certificates, lists the prerequisites, then covers four phases: Upload the certificate files, Confirm the certificate and private key match, Configure the certificate in Traefik, and Bind the certificate to a hostname. Binding relies on Server Name Indication (SNI), the part of the TLS handshake in which the client states the hostname it is requesting, allowing one Traefik instance to serve several certificates. The article closes with validation steps and common failure points.

How Traefik Loads Certificates

Traefik reads certificates from its dynamic configuration, which is a set of YAML Ain't Markup Language (YAML) files that Traefik watches and reloads. A certificate is made available in one file, and a router in a second file states which hostname should use TLS. Traefik then matches an incoming connection to a router by hostname and presents the matching certificate. The certificate is never uploaded through a console; the files on disk are the configuration.

Prerequisites

• Traefik installed and running, with a dynamic configuration directory that Traefik watches, and a websecure entry point listening on port 443.
• Your issued server certificate including the full chain, and the matching private key, as separate files.
• The Domain Name System (DNS) hostname the certificate was issued for, for example example.domain.com, resolving to the Traefik host.
• Shell access to the Traefik host with sudo rights.

A Note on Paths in This Article

The examples use a Docker deployment, which is the most common way Traefik is run. Certificate files are placed at certs on the host, and that directory is mounted into the container as /certs. The host path appears in the shell commands; the container path appears inside the configuration files, because Traefik reads them from inside the container. If you run Traefik directly on the host rather than in a container, use the same path in both places.

Upload the Certificate Files

This phase places the certificate and private key on the Traefik host with permissions that protect the key.

Step 1 — Copy the Files to the Host

Copy the certificate and private key into the certificate directory.

sudo cp server.crt /opt/traefik/certs/
sudo cp server.key /opt/traefik/certs/

Step 2 — Apply File Permissions

Restrict the private key so that only the owner can read it. The certificate itself is public and may remain readable.

sudo chmod 644 /opt/traefik/certs/server.crt
sudo chmod 600 /opt/traefik/certs/server.key

Confirm the Certificate and Private Key Match

This phase verifies that the two files are a matching key pair before Traefik is asked to load them. A mismatch is the most common cause of a failed certificate load.

Step 3 — Print the Public Key Hash from the Certificate

openssl x509 -in /opt/traefik/certs/server.crt -noout -pubkey | openssl sha256

Step 4 — Print the Public Key Hash from the Private Key

sudo openssl pkey -in /opt/traefik/certs/server.key -pubout | openssl sha256

Step 5 — Compare the Two Hashes

The two hash values must be identical. If they differ, the certificate and private key are not a pair; do not continue until you have the correct key.

Configure the Certificate in Traefik

This phase adds the certificate to the Traefik dynamic configuration so Traefik loads it.

Step 6 — Create or Update the TLS Configuration File

Edit tls.yml and add the certificate and key paths as Traefik sees them.

tls:
  certificates:
    - certFile: /certs/server.crt
      keyFile: /certs/server.key

Bind the Certificate to a Hostname

This phase creates the router that tells Traefik which hostname should be served over TLS. Without a router, the certificate is loaded but never presented.

Step 7 — Create or Update the Router Configuration File

Edit router.yml and define an HTTPS router for your hostname. Replace example.domain.com with the hostname on your certificate, and replace the service with the service that should receive the traffic.

http:
  routers:
    https-router:
      entryPoints:
        - websecure
      rule: "Host(`example.domain.com`)"
      service: noop@internal
      tls: {}

Step 8 — Reload Traefik

Traefik reloads dynamic configuration files automatically in most deployments. If your instance does not pick up the change, restart it.

sudo docker restart traefik

How to Verify Success

From a client system, open a TLS connection to the hostname and inspect what Traefik presents.

openssl s_client -connect example.domain.com:443 -servername example.domain.com

The binding is correct when the certificate returned is the one you installed, the issuer is the Certificate Authority (CA) that issued it, and the full chain is included. You can also open the address in a browser and confirm that the connection is secure, the certificate is valid, the hostname matches, and the chain is trusted.

Troubleshooting

Issue: The Two Public Key Hashes in Step 3 and Step 4 Do Not Match

Cause: The certificate and the private key are from different key pairs, usually because the key from an earlier Certificate Signing Request (CSR) was used with a newer certificate.
Solution: Locate the private key that was generated with the CSR used for this certificate order. If that key is not available, reissue the certificate using a new CSR and its matching key.

Issue: Traefik Starts but Presents a Default Self-Signed Certificate

Cause: Traefik could not load the configured certificate, or no router matches the requested hostname, so the built-in default certificate is served instead.
Solution: Confirm the paths in tls.yml are the paths as seen by Traefik, not the host paths, and confirm the Host rule in router.yml matches the name the client requested.

Issue: The Connection Is Refused or Times Out

Cause: The websecure entry point is not listening on port 443, or the port is not published from the container or allowed through the firewall.
Solution: Confirm the entry point configuration, confirm port 443 is published, and confirm the host firewall permits inbound traffic on that port.

Frequently Asked Questions

Can Traefik Serve More Than One Certificate?

Yes. Add further entries under certificates in tls.yml and a router for each hostname. Traefik selects the certificate using the hostname supplied by Server Name Indication (SNI).

Do I Need to Restart Traefik After Replacing a Renewed Certificate?

Usually not. Traefik watches the dynamic configuration directory and reloads changes. If the file paths are unchanged and Traefik does not pick up a replaced file, restart the instance.

Where Does the Certificate Chain Go?

Include the intermediate certificates in the same file as the server certificate, in the certFile the configuration references. Traefik presents the file contents as supplied.