26.09.2025 Problem:
A client deploying Harbor, the open-source container registry, wanted to replace the default Hossted-assigned domain with their own custom domain. Despite following setup instructions, Harbor continued to resolve to the old hostname. This resulted in SSL certificate mismatch errors, failed authentication requests, and missing features in the UI such as Proxy Cache and Helm chart management.
Process:
Step 1: Verify DNS and Hostname Configuration
DNS and hostname mappings were checked to ensure they correctly pointed to the intended custom domain.
Step 2: Review Harbor Configuration Files
The Harbor configuration files (harbor.yml, .env, docker-compose.yml) were inspected, and the EXT_ENDPOINT variable was found to still reference the old default domain.
Step 3: Validate SSL Certificate Setup
SSL certificates were reissued with Let’s Encrypt to match the new domain.
Step 4: Explore Related Issues
Additional concerns such as log port exposure, data storage requirements, and feature availability were reviewed.
Step 5: Assess Harbor Version
It was determined that the Harbor version in use was outdated, preventing access to Proxy Cache and the latest Helm chart capabilities.
Solution:
To resolve issues with Harbor running under the wrong hostname, the registry must be configured to use the correct custom domain. This requires updating Harbor’s configuration files, reissuing SSL certificates to match the domain, and restarting services so all components align.
For scalability, Harbor should be connected to external storage by mounting a dedicated disk to /data. This ensures sufficient space for growing image libraries and simplifies future maintenance.
Security can be strengthened by limiting access to logging and management ports, allowing only trusted internal networks.
Finally, upgrading to a recent Harbor release, such as v2.14, provides access to essential features. The upgrade introduces Proxy Cache for faster image pulls and replaces the deprecated ChartMuseum with the modern helm push workflow for Helm chart management.
Conclusion:
Through structured troubleshooting and targeted remediation, the client successfully transitioned Harbor to a production-ready setup. They now have a secure custom domain with valid SSL certificates, scalable external data storage, hardened network security, and access to modern Harbor features such as Proxy Cache and updated Helm chart support. This engagement not only solved the immediate problem but also positioned the client with a modern, secure, and scalable Harbor deployment that can grow alongside their infrastructure needs.