Skip to content

Certificate Management

Jump to bottom
fuomag9 edited this page Jul 23, 2026 · 6 revisions

Certificate Management

Manage automatic ACME certificates and imported custom certificates in Caddy Proxy Manager.

Table of Contents

  1. How Certificates Work
  2. Certificates Page Overview
  3. ACME Certificates
  4. Import Custom Certificates
  5. CA Certificates
  6. Renewal and Monitoring
  7. Security Considerations
  8. Troubleshooting

How Certificates Work

Caddy Proxy Manager supports three certificate paths:

  1. Automatic ACME (recommended)
  • Caddy obtains and renews certificates automatically (Let's Encrypt / ZeroSSL)
  • Used when a proxy host is set to Managed by Caddy (Auto)
  1. Imported custom certificates
  • You provide certificate PEM + private key PEM
  • Use for internal CAs, pre-issued wildcard certs, or compliance-driven workflows
  1. Built-in CA certificates
  • Generate your own CA root and issue internal client certificates
  • Useful for mTLS or testing without a third-party CA

Certificates Page Overview

The Certificates page has three tabs:

  1. ACME Certificates
  • Proxy hosts currently using automatic certificate management
  • Shows domains and host enabled/disabled status
  • Server-side paginated
  1. Imported Certificates
  • Custom certificates stored in the application database
  • Shows issuer, expiry, covered domains, and which hosts use each cert
  1. CA Certificates
  • Internal CA roots you have created
  • Issue and manage client certificates signed by each CA
  • Download CA cert, issue new client certs, view existing issued certs

ACME Certificates

What is shown

For each auto-managed proxy host, the table displays:

  • Proxy host name
  • Domains
  • Host enabled/disabled status

Caddy manages ACME certificate issuance and renewal entirely on its own. The ACME tab lists which proxy hosts use automatic certificates so you can verify coverage.

Pagination

ACME table pagination is server-side.

  • Default page size: 25
  • URL param: ?page=N

Import Custom Certificates

Use custom import when ACME is not suitable.

Import flow

  1. Open Certificates.
  2. Scroll to Import Custom Certificate.
  3. Provide:
    • Certificate Name
    • Domains (one per line)
    • Certificate PEM (full chain recommended)
    • Private Key PEM
  4. Click Import Certificate.

Manage imported certs

For each imported certificate, you can:

  • Review issuer and expiry
  • See covered domains
  • See which proxy hosts currently reference it
  • Update fields
  • Delete the certificate

When editing, keep certificate/key pairs matched.

CA Certificates

The built-in CA lets you create internal certificate authorities and issue client certificates.

Create a CA

  1. Open Certificates → CA Certificates.
  2. Click Create CA Certificate.
  3. Provide a name and optional metadata (organization, country, etc.).
  4. Click Create.

The CA root certificate can be downloaded and installed in browsers or systems that need to trust certificates issued by this CA.

Issue a Client Certificate

  1. Click the menu on a CA row and select Issue Client Certificate.
  2. Provide a name (used as the Common Name).
  3. Click Issue.
  4. Download the issued certificate and private key — they are not stored server-side after download.

Manage Issued Certificates

Click View Issued Certs on a CA row to list all certificates issued by that CA, including expiry status.

When to use the built-in CA

  • mTLS (mutual TLS) between services inside a trusted network
  • Internal testing without purchasing a certificate
  • Short-lived client credentials that need to be revoked quickly

Renewal and Monitoring

ACME certificates

  • Renewed automatically by Caddy
  • Renewal attempts start before expiration
  • No manual renew action is usually required

Imported certificates

  • Not auto-renewed
  • You must replace them before expiry

Operational checks

Caddy logs:

docker compose logs caddy | grep -i acme

Public endpoint check:

echo | openssl s_client -connect your-domain.com:443 2>/dev/null | openssl x509 -noout -issuer -dates

Security Considerations

Private key storage

Imported private keys are stored in SQLite and are not encrypted at rest by default.

Recommendations:

  • Restrict data volume/file permissions
  • Encrypt backups
  • Rotate imported certificates regularly
  • Limit host access to backup artifacts

Certificate source of truth

  • ACME cert material lives in Caddy's data volume
  • Imported cert material lives in the app database

Troubleshooting

Certificate issuance fails

Checks:

  1. Domain resolves to your public IP
  2. Ports 80/443 reachable (for HTTP-01/TLS-ALPN-01)
  3. DNS provider configured in Settings → DNS Providers for wildcard or internal-only domains (see DNS Provider Configuration)
  4. ACME email configured in Settings

Imported cert rejected or unusable

Verify key/cert match:

openssl x509 -noout -modulus -in cert.pem | openssl md5
openssl rsa  -noout -modulus -in key.pem  | openssl md5

Hashes must match.

Related Documentation

Need help? Open an issue with logs and non-sensitive certificate metadata (never share private keys).

Clone this wiki locally