# Harbor Container Registry

> Enterprise-class container registry with vulnerability scanning, image signing, and replication.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: harbor-core, harbor-portal, trivy, postgresql, redis, nginx
- Tags: harbor, registry, docker, security, enterprise
- Source: https://docker.recipes/devops/harbor-registry-stack

## Overview

Harbor Container Registry is an open-source, enterprise-grade container registry that extends Docker Distribution with security-focused features including vulnerability scanning, content signing, and role-based access control. Originally created by VMware and now a CNCF graduated project, Harbor addresses the security and governance gaps in basic container registries by providing comprehensive image lifecycle management with built-in security scanning via Trivy, multi-tenancy support, and replication capabilities for distributed deployments.

This Harbor deployment stack combines the Harbor core services with PostgreSQL for metadata storage, Redis for caching and session management, Trivy for vulnerability scanning, and NGINX as a reverse proxy. The architecture separates concerns across multiple specialized containers: harbor-core handles API operations and authentication, harbor-portal provides the web interface, jobservice manages background tasks like garbage collection and replication, while registryctl manages the underlying Docker registry storage. This multi-service approach enables horizontal scaling and independent updates of components.

This configuration is ideal for organizations requiring private container registries with enterprise security features, development teams needing vulnerability scanning integrated into their CI/CD pipelines, and compliance-driven environments where image provenance and security scanning are mandatory. The stack provides a self-hosted alternative to managed registry services while offering more advanced security and governance features than basic Docker Registry deployments, making it particularly valuable for air-gapped environments, multi-tenant scenarios, and organizations with strict data sovereignty requirements.

## Features

- Trivy-powered vulnerability scanning with CVE database integration and severity-based policy enforcement
- Content signing and trust verification using Docker Content Trust and Notary integration
- Role-based access control with project-level permissions and LDAP/OIDC authentication support
- Multi-registry replication for disaster recovery and geographically distributed deployments
- Webhook notifications for image push/pull events and vulnerability scan results
- Project quotas and resource management with storage usage tracking and limits
- Comprehensive audit logging for compliance with detailed user activity tracking
- Garbage collection automation for efficient storage management and cleanup policies

## Use cases

- Enterprise container registry with security scanning for large development teams requiring vulnerability assessment
- Air-gapped environments needing private registry with offline vulnerability database updates
- Multi-tenant SaaS platforms requiring project isolation and granular access controls per customer
- Compliance-driven organizations needing audit trails and image signing for regulatory requirements
- Hybrid cloud deployments requiring image replication between on-premises and cloud registries
- DevSecOps pipelines integrating vulnerability scanning gates before production deployments
- Container supply chain security implementations requiring image provenance and trust verification

## Prerequisites

- Minimum 4GB RAM and 2 CPU cores for Harbor core services plus database and cache components
- 50GB+ available storage for container images, vulnerability database, and PostgreSQL data
- Ports 80 and 443 available for HTTP/HTTPS access through NGINX reverse proxy
- SSL certificates configured for production HTTPS access and Docker client trust
- Understanding of container registry concepts, Docker authentication, and certificate management
- Network connectivity for Trivy vulnerability database updates and image replication if required

## docker-compose.yml

```yaml
services:
  log:
    image: goharbor/harbor-log:latest
    volumes:
      - harbor_log:/var/log/docker/:z
      - ./config/log/logrotate.conf:/etc/logrotate.d/logrotate.conf:z
    networks:
      - harbor-net
    restart: unless-stopped

  registry:
    image: goharbor/registry-photon:latest
    volumes:
      - registry_data:/storage:z
      - ./config/registry/config.yml:/etc/registry/config.yml:z
    networks:
      - harbor-net
    depends_on:
      - log
    restart: unless-stopped

  registryctl:
    image: goharbor/harbor-registryctl:latest
    volumes:
      - registry_data:/storage:z
      - ./config/registry/config.yml:/etc/registry/config.yml:z
      - ./config/registryctl/config.yml:/etc/registryctl/config.yml:z
    networks:
      - harbor-net
    restart: unless-stopped

  postgresql:
    image: goharbor/harbor-db:latest
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - database:/var/lib/postgresql/data:z
    networks:
      - harbor-net
    restart: unless-stopped

  core:
    image: goharbor/harbor-core:latest
    environment:
      CORE_KEY: ${CORE_KEY}
      _REDIS_URL_CORE: redis://redis:6379/0
      SYNC_REGISTRY: "false"
      CHART_CACHE_DRIVER: redis
      _REDIS_URL_REG: redis://redis:6379/1
      PORTAL_URL: http://portal:8080
      REGISTRY_URL: http://registry:5000
      TOKEN_SERVICE_URL: http://core:8080/service/token
      HARBOR_ADMIN_PASSWORD: ${HARBOR_ADMIN_PASSWORD}
      DATABASE_TYPE: postgresql
    volumes:
      - core_data:/data:z
      - ./config/core/app.conf:/etc/core/app.conf:z
    networks:
      - harbor-net
    depends_on:
      - log
      - registry
      - postgresql
      - redis
    restart: unless-stopped

  portal:
    image: goharbor/harbor-portal:latest
    networks:
      - harbor-net
    depends_on:
      - log
      - core
    restart: unless-stopped

  jobservice:
    image: goharbor/harbor-jobservice:latest
    volumes:
      - job_logs:/var/log/jobs:z
      - ./config/jobservice/config.yml:/etc/jobservice/config.yml:z
    networks:
      - harbor-net
    depends_on:
      - core
    restart: unless-stopped

  redis:
    image: goharbor/redis-photon:latest
    volumes:
      - redis_data:/var/lib/redis
    networks:
      - harbor-net
    restart: unless-stopped

  trivy-adapter:
    image: goharbor/trivy-adapter-photon:latest
    environment:
      SCANNER_TRIVY_CACHE_DIR: /home/scanner/.cache/trivy
      SCANNER_TRIVY_REPORTS_DIR: /home/scanner/.cache/reports
    volumes:
      - trivy_cache:/home/scanner/.cache
    networks:
      - harbor-net
    restart: unless-stopped

  proxy:
    image: goharbor/nginx-photon:latest
    ports:
      - "80:8080"
      - "443:8443"
    volumes:
      - ./config/nginx:/etc/nginx:z
    networks:
      - harbor-net
    depends_on:
      - registry
      - core
      - portal
    restart: unless-stopped

volumes:
  harbor_log:
  registry_data:
  database:
  core_data:
  job_logs:
  redis_data:
  trivy_cache:

networks:
  harbor-net:
    driver: bridge
```

## .env

```bash
# Harbor Admin Password
HARBOR_ADMIN_PASSWORD=Harbor12345

# PostgreSQL
POSTGRES_PASSWORD=secure_postgres_password

# Core Secret Key
CORE_KEY=your_32_char_secret_key_here
```

## Usage notes

- Harbor UI at https://localhost
- Default login: admin / Harbor12345
- Includes Trivy vulnerability scanning
- Use harbor installer for full setup

## Troubleshooting

- Harbor UI shows 'Internal Server Error': Check PostgreSQL connectivity and ensure database initialization completed successfully in logs
- Docker login fails with certificate errors: Verify SSL certificates are properly configured in NGINX and trusted by Docker daemon
- Trivy scanner shows outdated vulnerability database: Check internet connectivity and restart trivy-adapter container to force database update
- Job service fails with Redis connection errors: Verify Redis container is healthy and check Redis URL configuration in core service environment
- Registry push fails with 'insufficient storage': Check available disk space and configure garbage collection policies to free unused image layers
- LDAP authentication not working: Verify LDAP server connectivity and check Harbor core logs for authentication binding errors

