How to change Certificate on a Docker Container

Learn how to manually replace TLS certificate files in a Docker container, choose persistent mounts, reload or restart the workload, and verify the served certificate.

Docker does not define one application certificate store. The image decides which files and reload command matter. A file copied into a running container's writable layer is also lost when the container is recreated, so durable deployments normally use a bind mount, named volume, secret, or image/redeploy workflow.

Before you begin

Identify the container, in-container paths, process user, required certificate format, health check, reload signal/command, orchestration owner, and persistence model. Back up the old material without printing the private key into logs.

Step-by-step certificate replacement

Prefer updating the host source of an existing read-only bind mount or secret, then redeploying through Compose/orchestration. If the design intentionally stores files in the container, copy them to an existing directory:
```
docker cp fullchain.pem <container>:/etc/service/tls/fullchain.pem
docker cp private.key <container>:/etc/service/tls/private.key
```

Set ownership and mode inside the container using the product's documented account:

docker exec <container> chown <uid>:<gid> /etc/service/tls/private.key
docker exec <container> chmod 0600 /etc/service/tls/private.key

Run the application's configuration test and reload command with docker exec. If it has no supported reload, restart the container:

docker exec <container> <configuration-test-command>
docker exec <container> <reload-command>
# or: docker restart <container>

Update the Compose file, secret source, image, or other desired state so the next recreation does not restore the old certificate.

Product-specific considerations

docker cp extracts an archive through the Engine API and does not update an image. Container restarts cause a brief outage unless replicas and health-aware routing are used. Compose secrets are mounted as files and are preferable to environment variables for key material, but changing their source still needs the application's documented reload/recreation behavior.

Verify the new certificate

Inspect the in-container file fingerprint and the certificate served through the published port. Recreate the container in a maintenance environment to prove the new desired state survives, rather than only testing the current writable layer.

Rollback

Restore the previous mounted source/secret or copy the old files back, then run the same reload/restart. Roll back the Compose/image definition as well.

Common problems

Replacement exists only in the disposable container layer.
Host paths are confused with in-container paths.
The process user cannot read the key.
The main process ignores a generic signal or reload command.
One replica behind the published service remains on the old certificate.

Automating certificate replacement with aethercert

The aethercert Docker target copies certificate, chain, and key to configured paths inside a running container, then executes a configured in-container reload command or restarts the container. It does not redesign the container's persistence model.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.