# Harbor Container Registry

> Enterprise container registry with security scanning.

- Category: DevOps & CI/CD
- Difficulty: advanced
- Components: harbor-core, harbor-db, redis
- Tags: harbor, registry, containers, security
- Source: https://docker.recipes/devops/harbor

## Overview

Harbor is an open-source, cloud-native container registry that provides enterprise-grade features for storing, signing, and scanning container images. Originally developed by VMware and now a CNCF graduated project, Harbor extends the standard Docker Registry with security scanning, role-based access control, image replication, and comprehensive audit logging. It has become the go-to solution for organizations requiring a self-hosted container registry with advanced security and governance capabilities.

This deployment creates a complete Harbor registry environment using three core services: harbor-core as the main registry application, harbor-db (PostgreSQL) for metadata and configuration storage, and redis for caching and job queuing. The harbor-core service handles image storage, API requests, and web UI functionality, while PostgreSQL maintains user accounts, project configurations, and vulnerability scan results. Redis accelerates performance by caching frequently accessed data and managing background job queues for image scanning and garbage collection tasks.

This configuration is ideal for development teams, DevOps engineers, and organizations seeking a private container registry with built-in security features. Unlike hosted solutions, this self-managed Harbor instance provides complete control over your container images, enables compliance with data residency requirements, and offers advanced features like vulnerability scanning with Trivy integration, content signing, and multi-registry replication without per-image costs or bandwidth limitations.

## Features

- Trivy-powered vulnerability scanning with CVE database updates and security policy enforcement
- Role-based access control (RBAC) with project-level permissions and LDAP/OIDC integration
- Content signing and trust verification using Docker Content Trust and Notary
- Image replication across multiple Harbor registries for disaster recovery and geo-distribution
- Automated garbage collection with configurable retention policies and storage quota management
- Comprehensive audit logging with detailed tracking of user actions and image operations
- Project quotas and resource limits with storage usage monitoring and alerts
- Webhook notifications for image push/pull events and vulnerability scan results

## Use cases

- Enterprise container registry for organizations requiring security scanning and compliance reporting
- Multi-team development environments with project isolation and granular access controls
- CI/CD pipelines needing vulnerability scanning gates before production deployments
- Air-gapped or regulated environments requiring on-premises container image storage
- Multi-site deployments using Harbor replication for image synchronization across regions
- Container image lifecycle management with automated cleanup and retention policies
- Security-focused development workflows requiring signed images and trust verification

## Prerequisites

- Minimum 4GB RAM recommended (2GB absolute minimum for basic functionality)
- Docker Engine 20.10+ and Docker Compose v2 for proper container orchestration
- Port 8080 available for Harbor web UI and Docker Registry API access
- Sufficient disk space for container images and PostgreSQL database (10GB+ recommended)
- Basic understanding of Docker Registry concepts and container image management
- Network connectivity for Trivy vulnerability database updates and CVE feeds

## docker-compose.yml

```yaml
services:
  harbor-db:
    image: goharbor/harbor-db:latest
    container_name: harbor-db
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - harbor_db:/var/lib/postgresql/data

  harbor-core:
    image: goharbor/harbor-core:latest
    container_name: harbor-core
    restart: unless-stopped
    depends_on:
      - harbor-db
      - redis
    environment:
      CONFIG_PATH: /etc/harbor/app.conf
    ports:
      - "8080:8080"
    volumes:
      - harbor_data:/data

  redis:
    image: redis:7-alpine
    container_name: harbor-redis
    restart: unless-stopped
    volumes:
      - harbor_redis:/data

volumes:
  harbor_db:
  harbor_data:
  harbor_redis:
```

## .env

```bash
DB_PASSWORD=changeme
# Use Harbor installer for full deployment
```

## Usage notes

- Docs: https://goharbor.io/docs/
- For production use official installer: https://github.com/goharbor/harbor/releases
- Access at http://localhost:8080 - default: admin/Harbor12345
- Image vulnerability scanning with Trivy integration
- Push images: docker tag myimage localhost/library/myimage && docker push localhost/library/myimage
- Replication policies for multi-site registry sync

## Troubleshooting

- Harbor core fails to start with database connection errors: Ensure harbor-db container is fully initialized before harbor-core starts, check DB_PASSWORD environment variable
- Image push fails with 'unauthorized' errors: Verify authentication using docker login localhost:8080 with admin/Harbor12345 credentials
- Vulnerability scanning not working: Check harbor-core container logs for Trivy database download issues, ensure internet connectivity for CVE updates
- Web UI shows 500 internal server errors: Verify redis container is running and accessible, check harbor-core logs for Redis connection failures
- Docker daemon cannot connect to registry: Ensure Docker daemon is configured to allow insecure registries for localhost:8080 or configure TLS certificates
- Storage space issues with accumulated images: Configure garbage collection policies in Harbor UI under Administration > Garbage Collection

