If you run a self-hosted container registry, such as Harbor behind Nginx, you may encounter this frustrating error:
x509: certificate signed by unknown authority
I wrote a practical guide explaining what actually causes this error and how to fix it securely:
https://oscarchou.com/posts/troubleshoot/docker-x509-certificate-error-in-self-hosted-registry/
The most important detail is easy to overlook: although the user runs docker pull, the Docker CLI does not connect to the registry directly. It delegates the request to the Docker daemon, which acts as the TLS client and verifies the certificate presented by Nginx.
If the daemon cannot find the internal CA in its trusted certificates, it aborts the TLS handshake before the request reaches Harbor.
The guide uses diagrams to explain:
How the Harbor, Nginx, and Docker components communicate
Why the Docker daemon performs certificate verification
Where Docker looks for trusted CAs
How to install the CA under
/etc/docker/certs.dWhy
insecure-registriesis not a secure solution
If you are troubleshooting TLS for a self-hosted registry, I hope this guide saves you some time.