Setting Up Harbor for Enterprise Docker Image Management

Harbor is an enterprise-grade private container registry that provides comprehensive capabilities for storing container images, managing users, controlling access, and scanning for security vulnerabilities. This guide walks through deploying Harbor in a production-ready configuration.

1. System Requirements

Before beginning the installation, ensure your server meets these minimum specifications:

• Operating System: Linux distribution (CentOS 7+, Ubuntu 20.04+, Rocky Linux 9+, or similar)
• Processor: Dual-core CPU or higher
• Memory: 4GB minimum (8GB recommended for production)
• Storage: 50GB available space minimum, expandable based on image repository size
• Docker Engine: Version 28.0.0 or newer
• Docker Compose: Version 2.0 or newer

2. Installing Docker and Docker Compose

Start by installing the Docker engine using the official installation script. This approach works across most Linux distributions and handles all dependencies automatically:

curl -fsSL https://get.docker.com | bash
systemctl enable docker --now

After installation, verify that both the Docker client and server components are running correctly:

docker version

Confirm that the output shows version 28.0.0 or higher for both client and server components. If the version is lower, consult the Docker documentation for manual installation instructions.

Next, install Docker Compose to manage multi-container Harbor deployments. The following commands download the latest stable release and make it executable:

mkdir -p /usr/local/lib/docker/cli-plugins
curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 -o /usr/local/lib/docker/cli-plugins/docker-compose
chmod +x /usr/local/lib/docker/cli-plugins/docker-compose
docker compose version

3. Obtaining Harbor

Download the offline installer package, which includes all necessary Harbor components bundled together. This approach eliminates dependency issues during installation:

wget https://github.com/goharbor/harbor/releases/download/v2.9.0/harbor-offline-installer-v2.9.0.tgz
tar -zxvf harbor-offline-installer-v2.9.0.tgz
cd harbor

The offline installer is preferred for production deployments as it pulls no external resources during the installation process, reducing network dependency and improving reliability.

4. Configuring Harbor

The Harbor installation includes a template configuration file that you must customize for your environment:

cp harbor.yml.tmpl harbor.yml
vi harbor.yml

Modify the essential configuration parameters to match your deployment requirements. The hostname should point to a resolvable domain name or IP address that clients will use to access the registry:

hostname: registry.internal.company.local

http:
  port: 80

harbor_admin_password: "SecurePassword123!"

The administrator password specified here will be used for the initial login to the Harbor web interface. Choose a strong password and change it immediately after first login in a production environment.

5. Starting Harbor

With the configuration complete, initiate the Harbor installation process:

./install.sh

The installer will deploy all Harbor components as Docker containers. Once completed, access the web interface by navigating to the configured hostname. The default credentials for initial access are username admin with the password specified in the configuration file.

6. Configuring Docker Client Access

Docker clients must explicitly trust your Harbor instance if you are using HTTP rather than HTTPS. Create or edit the Docker daemon configuration to whitelist your registry:

vi /etc/docker/daemon.json

Add your Harbor hostname to the insecure-registries list:

{
  "insecure-registries": ["registry.internal.company.local"]
}

Restart the Docker service to apply these changes:

systemctl restart docker

7. Pushing and Pulling Images

Authenticate to your private registry using the admin credentials configured during installation:

docker login registry.internal.company.local

Create a new project through the Harbor web interface before pushing images. Navigate to Projects, click New Project, and define a project name such as application-images.

Tag an existing local image with the fully qualified registry path:

docker tag ubuntu:latest registry.internal.company.local/application-images/ubuntu:latest

Push the tagged image to your private registry:

docker push registry.internal.company.local/application-images/ubuntu:latest

Retrieve images from the registry using the standard pull command:

docker pull registry.internal.company.local/application-images/ubuntu:latest

8. Enabling HTTPS with Self-Signed Certificates

For production environments, HTTPS is strongly recommended to secure communication between Docker clients and the registry. Generate a self-signed certificate using OpenSSL:

mkdir -p /certs && cd /certs
openssl req -newkey rsa:4096 -nodes -sha256 -keyout registry.key -x509 -days 365 -out registry.crt

When prompted for the Common Name, enter the exact hostname you configured for Harbor. This certificate must match the hostname exactly for TLS verification to succeed.

Update the Harbor configuration to enable HTTPS:

hostname: registry.internal.company.local

https:
  port: 443
  certificate: /certs/registry.crt
  private_key: /certs/registry.key

Apply the new configuration by restarting Harbor:

docker compose down
docker compose up -d

Configure Docker to trust the self-signed certificate by copying it to the appropriate directory structure:

mkdir -p /etc/docker/certs.d/registry.internal.company.local
cp /certs/registry.crt /etc/docker/certs.d/registry.internal.company.local/ca.crt
systemctl restart docker

9. Enabling Security Scanning

Harbor includes built-in vulnerability scanning through Clair integration. Enable this feature by modifying the configuration file:

clair:
  enabled: true

Restart Harbor to activate the scanner:

docker compose down
docker compose up -d

Once enabled, all pushed images will automatically undergo security scanning. You can review scan results through the Harbor web interface, which provides detailed vulnerability reports and remediation recommendations.

10. Image Signing with Notary

For environments requiring additional security guarantees, Harbor supports image signing through Notary. This ensures that images have not been tampered with during storage or transit:

notary:
  enabled: true

When enabled, content trust allows you too verify that pulled images originate from your trusted build pipeline. Users must explicitly enable Docker content trust to benefit from this protection.

11. Operational Management Commands

Use these commands to manage your Harbor deployment effectively. Monitor the status of all Harbor containers:

docker compose ps

Stop all Harbor services while preserving data volumes:

docker compose down

Restart Harbor services after configuration changes:

docker compose up -d

Review application logs for troubleshooting purposes:

docker logs -f harbor-core

12. Deployment Considerations

Enterprise deployments benefit from Harbor's replication capabilities, which allow distributing images across multiple registry instances for high availability. Consider implementing webhook integrations to trigger CI/CD pipeline actions based on repository events. Regular database and storage backups ensure recoverability in case of infrastructure failures.

The metrics endpoint at /api/v2.0/metrics integrates with Prometheus for monitoring Harbor performance and resource utilization over time.