sharenet/registry/README.md

# Harbor Registry Configuration

This folder contains the configuration files for the Harbor Registry setup used in the CI/CD pipeline.

## Files

- `docker-compose.yml` - Docker Compose configuration for Harbor services
- `harbor.yml` - Harbor configuration file
- `README.md` - This file

## Architecture

This setup uses a hybrid approach for optimal maintainability and security:

### Repository Files (Version Controlled)
- Configuration files in `/opt/APP_NAME/registry/`
- Easy to update via git pull
- Version controlled and tracked

### System Files (Not Version Controlled)
- SSL certificates in `/etc/ssl/registry/`
- Authentication files in `/etc/registry/auth/`
- Registry data in Docker volume `/var/lib/registry`

## Usage

The setup process will:

1. Clone the repository to `/opt/APP_NAME/`
2. Create system directories for certificates and auth
3. Generate SSL certificates in `/etc/ssl/registry/`
4. Create authentication files in `/etc/registry/auth/`
5. Start the registry services using the hybrid configuration

## Configuration Notes

- **Registry**: Runs on port 5000 with HTTPS
- **Nginx**: Provides SSL termination and reverse proxy on port 8080
- **Registry UI**: Web interface accessible via nginx on port 8080
- **Authentication**: Uses htpasswd for push authentication
- **Storage**: Uses Docker volume for persistent data
- **Configuration**: Version controlled in repository
- **Certificates**: Stored in system SSL directory

## Security

- SSL certificates are self-signed and stored in system SSL directory
- Authentication files are stored in system auth directory
- Configuration is version controlled and easily auditable
- All communication uses HTTPS
- Clear separation between config, auth, and data 

# Harbor Registry Setup

This directory contains the configuration for Harbor, an enterprise-grade container registry that provides:

- **Public read access** - Anyone can pull images without authentication
- **Authenticated write access** - Only authenticated users can push images
- **Web UI** - Modern web interface for managing images
- **Vulnerability scanning** - Built-in security scanning with Trivy
- **Role-based access control** - Fine-grained permissions
- **Multi-tenancy** - Project-based organization

## Prerequisites

1. Docker and Docker Compose installed
2. SSL certificates for HTTPS (recommended for production)
3. At least 4GB RAM and 10GB disk space

## Configuration

### 1. Update Configuration Files

Before starting Harbor, update the following files:

- `harbor.yml`: Update `hostname` and `harbor_admin_password`
- `docker-compose.yml`: Update secrets and passwords

### 2. SSL Certificates

Place your SSL certificates in `/etc/ssl/registry/`:
- `registry.crt` - SSL certificate
- `registry.key` - SSL private key

### 3. Environment Variables

Set the following environment variables:
```bash
export HARBOR_HOSTNAME=YOUR_CI_CD_IP
export HARBOR_ADMIN_PASSWORD=your-secure-password
export DB_PASSWORD=your-db-password
```

## Installation

1. **Stop existing registry** (if running):
   ```bash
   docker compose down
   ```

2. **Start Harbor**:
   ```bash
   docker compose up -d
   ```

3. **Wait for startup** (can take 2-3 minutes):
   ```bash
   docker compose logs -f
   ```

## Initial Setup

1. **Access Harbor UI**: https://YOUR_CI_CD_IP:8080
2. **Login with default credentials**:
   - Username: `admin`
   - Password: `Harbor12345` (or your configured password)

3. **Change admin password** on first login

## Configuration for Public Read, Authenticated Write

### 1. Create a Public Project

1. Go to **Projects** → **New Project**
2. Set **Project Name**: `public`
3. Set **Access Level**: `Public`
4. Click **OK**

### 2. Create a Private Project (for authenticated writes)

1. Go to **Projects** → **New Project**
2. Set **Project Name**: `private`
3. Set **Access Level**: `Private`
4. Click **OK**

### 3. Create Users

1. Go to **Administration** → **Users** → **New User**
2. Create users with appropriate roles:
   - **Developer**: Can push/pull to private projects
   - **Guest**: Can only pull from public projects

## Usage

### Docker Login
```bash
docker login YOUR_CI_CD_IP:8080
```

### Push Images
```bash
# Tag your image
docker tag myimage:latest YOUR_CI_CD_IP:8080/public/myimage:latest

# Push to public project (requires authentication)
docker push YOUR_CI_CD_IP:8080/public/myimage:latest
```

### Pull Images
```bash
# Pull from public project (no authentication required)
docker pull YOUR_CI_CD_IP:8080/public/myimage:latest
```

## Security Features

- **Vulnerability Scanning**: Automatic CVE scanning with Trivy
- **Image Signing**: Content trust and image signing
- **RBAC**: Role-based access control
- **Audit Logs**: Complete audit trail of all operations

## Maintenance

### Backup
```bash
# Backup Harbor data
docker compose exec harbor-db pg_dump -U postgres registry > backup.sql
```

### Update
```bash
# Pull latest images
docker compose pull

# Restart services
docker compose up -d
```

### Logs
```bash
# View all logs
docker compose logs

# View specific service logs
docker compose logs harbor-core
```

## Troubleshooting

### Common Issues

1. **Startup takes too long**: Harbor needs time to initialize database and download vulnerability databases
2. **SSL certificate errors**: Ensure certificates are properly placed and have correct permissions
3. **Authentication issues**: Check user permissions and project access levels

### Health Check
```bash
# Check service status
docker compose ps

# Check Harbor health
curl -k https://YOUR_CI_CD_IP:8080/api/v2.0/health
```

## Resources

- [Harbor Documentation](https://goharbor.io/docs/)
- [Harbor GitHub](https://github.com/goharbor/harbor)
- [CNCF Harbor](https://landscape.cncf.io/card-mode?category=container-registry&grouping=category&selected=harbor)