This topic describes recommended certificate lifetimes for development and production environments and provides steps for rotating TLS and mTLS certificates. It also explains how to manage certificate hostnames during regeneration.

Recommended certificate lifetimes

The following table summarizes typical certificate lifetimes and production recommendations:
Certificate type Typical lifetime (development) Production recommendation
Self-signed development certificate 365 days Use shorter lifetimes (90–180 days) or switch to an internal CA or ACME-based solution
Client mTLS certificate 180 days Rotate every 60–90 days with automation
Certificate authority (development profile) 1 year Use a managed CA service or internal PKI

Steps to rotate server TLS certificates

Perform the following steps to rotate TLS certificates:
  1. Use ACME, an internal PKI, or a development script to generate the new certificate and key.
  2. Place the certificate and key in the correct location:
    • For development, place them in the profile/certs/ directory.
    • For production, use a secure secret mount or a vault reference if externalized.
  3. Ensure that the configuration reflects the new certificate and key filenames.
  4. Perform a rolling restart using the following command:
    docker compose up -d
  5. Distribute new client certificates and maintain the CA trust chain until all clients are updated.

Manage certificate hostnames

When regenerating certificates with different hostnames or domains, follow these guidelines:
  • Development environment using mcpgen—Use the --extra-hostnames flag to include additional domains when generating certificates:
    ./mcpgen up --quick --tls --extra-hostnames api.example.com,staging.example.com

    Generated certificates include both localhost and the specified hostnames as Subject Alternative Names (SAN). Both .pem and .crt formats are generated for client compatibility.

  • Manual certificate generation—Use the same --extra-hostnames flag for manual generation:
    ./mcpgen up --quick --tls --extra-hostnames "api.example.com,staging.example.com
    For mTLS, include client certificates:
    ./mcpgen up --quick --mtls --extra-hostnames "api.example.com,staging.example.com"

Production considerations

Use the following guidelines when managing certificate hostnames in a production environment:
  • Plan hostname changes during scheduled maintenance windows.
  • Update DNS records before deploying new certificates.
  • Verify that all client applications can validate the new certificate hostnames.
  • Consider using wildcard certificates (for example, *.example.com) for flexibility across subdomains.