claude-code-router/harbor

Harbor Container Registry Setup

Complete Harbor container registry setup with HTTPS support for local Docker development and image management.

Overview

This Harbor deployment provides:

1. Secure HTTPS Access: TLS-enabled registry accessible via harbor.omniverseai.net
2. Docker Registry v2 API: Full compatibility with Docker CLI and Kubernetes
3. Web UI: Manage images, projects, and users via web interface
4. Local Performance: Direct LAN access for fast image push/pull operations

Current Configuration

Access Information

• Web UI: https://harbor.omniverseai.net (or http://192.168.1.83)
• Registry: harbor.omniverseai.net (HTTPS on port 443)
• Admin Credentials:
  • Username: admin
  • Password: admin123

Port Mapping

• HTTP: 80 → 8080 (internal)
• HTTPS: 443 → 8443 (internal)

DNS Configuration

Harbor uses local DNS resolution via /etc/hosts to avoid latency from cloud routing:

192.168.1.83 harbor.omniverseai.net

This allows direct LAN access while maintaining the production domain name.

Prerequisites

• Docker Desktop or OrbStack
• macOS with network access to 192.168.1.83
• OpenSSL (for certificate generation)

Quick Start

1. Start Harbor Services

# Start all Harbor services
docker-compose up -d

# Verify all services are healthy (wait ~30 seconds)
docker-compose ps

2. Configure Docker Client

For macOS/Linux:

# Create certificate directory
mkdir -p ~/.docker/certs.d/harbor.omniverseai.net

# Copy Harbor's CA certificate
cp /Users/brunogao/certs/harbor.omniverseai.net.pem \
   ~/.docker/certs.d/harbor.omniverseai.net/ca.crt

For Kubernetes/K3s nodes:

See configure-k8s-harbor.sh for automated containerd configuration.

3. Login and Test

# Login to Harbor
docker login harbor.omniverseai.net
# Username: admin
# Password: admin123

# Test with a sample image
docker pull hello-world
docker tag hello-world harbor.omniverseai.net/library/hello-world:latest
docker push harbor.omniverseai.net/library/hello-world:latest

SSL Certificate Configuration

Current Certificates

Harbor uses self-signed certificates located at:

• Certificate: /Users/brunogao/certs/harbor.omniverseai.net.pem
• Private Key: /Users/brunogao/certs/harbor.omniverseai.net-key.pem

Certificate Details

• Common Name (CN): harbor.omniverseai.net
• Subject Alternative Names (SANs):
  • DNS: harbor.omniverseai.net
  • DNS: *.omniverseai.net
  • IP: 192.168.1.83
• Validity: 365 days

Regenerating Certificates

If certificates expire or need renewal:

cd /Users/brunogao/certs

openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout harbor.omniverseai.net-key.pem \
  -x509 -days 365 \
  -out harbor.omniverseai.net.pem \
  -subj "/C=CN/ST=Beijing/L=Beijing/O=OmniverseAI/OU=IT/CN=harbor.omniverseai.net" \
  -addext "subjectAltName=DNS:harbor.omniverseai.net,DNS:*.omniverseai.net,IP:192.168.1.83"

# Copy to Harbor secret directory
cp harbor.omniverseai.net.pem /Users/brunogao/ops/data/harbor/secret/cert/server.crt
cp harbor.omniverseai.net-key.pem /Users/brunogao/ops/data/harbor/secret/cert/server.key

# Restart Harbor
docker-compose restart proxy

Configuration Files

Primary Configuration

• harbor.yml: Main Harbor configuration

  • Hostname: harbor.omniverseai.net
  • External URL: https://harbor.omniverseai.net
  • HTTPS enabled on port 8443 (mapped to 443)

• docker-compose.yml: Service orchestration

  • Port mappings: 80:8080, 443:8443
  • Volume mounts to /Users/brunogao/ops/data/harbor

• common/config/nginx/nginx.conf: Nginx proxy configuration

  • HTTP server on port 8080
  • HTTPS server on port 8443 with SSL

Environment Configuration

Harbor core service environment (common/config/core/env):

EXT_ENDPOINT=https://harbor.omniverseai.net
HARBOR_ADMIN_PASSWORD=admin123

Management Scripts

Harbor Operations

# Start Harbor
docker-compose up -d

# Stop Harbor
docker-compose down

# Restart specific service
docker-compose restart core
docker-compose restart proxy

# View logs
docker-compose logs -f core
docker-compose logs -f nginx

# Check service health
docker-compose ps

Admin Password Reset

If you need to reset the admin password:

# 1. Update password in harbor.yml
# harbor_admin_password: your-new-password

# 2. Clear existing password in database
docker-compose exec postgresql psql -U postgres -d registry \
  -c "UPDATE harbor_user SET password='', salt='' WHERE username='admin';"

# 3. Restart core to reinitialize
docker-compose restart core

# Core will automatically set the password from harbor.yml

Kubernetes Integration

Configure Containerd for K3s

Use the provided script to configure K3s nodes:

./configure-k8s-harbor.sh

This will:

• Install Harbor CA certificate to containerd
• Configure registry mirrors and authentication
• Restart containerd to apply changes

Manual K3s Configuration

For manual setup, see HARBOR_CLIENT_CONFIG.md.

Troubleshooting

Issue: "unauthorized" or "invalid credentials" when logging in

Solution:

# Reset admin password
docker-compose exec postgresql psql -U postgres -d registry \
  -c "UPDATE harbor_user SET password='', salt='' WHERE username='admin';"

docker-compose restart core

# Wait 10 seconds, then try login again with admin/admin123

Issue: "x509: certificate signed by unknown authority"

Solution:

# Ensure Docker trusts Harbor's certificate
mkdir -p ~/.docker/certs.d/harbor.omniverseai.net
cp /Users/brunogao/certs/harbor.omniverseai.net.pem \
   ~/.docker/certs.d/harbor.omniverseai.net/ca.crt

# For system-wide trust (macOS)
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain \
  /Users/brunogao/certs/harbor.omniverseai.net.pem

Issue: "connection refused" when accessing Harbor

Solution:

# Check if services are running
docker-compose ps

# Check if ports are listening
lsof -i :80
lsof -i :443

# Verify /etc/hosts entry
grep harbor.omniverseai.net /etc/hosts
# Should show: 192.168.1.83 harbor.omniverseai.net

# Restart Harbor
docker-compose down && docker-compose up -d

Issue: "dial tcp 192.168.1.83:8443: connect: connection refused"

This indicates Harbor is using the wrong EXT_ENDPOINT. Solution:

# Update core environment
vim common/config/core/env
# Change: EXT_ENDPOINT=https://harbor.omniverseai.net

# Force recreate core container
docker-compose up -d --force-recreate core

# Verify
docker-compose exec core env | grep EXT_ENDPOINT
# Should show: EXT_ENDPOINT=https://harbor.omniverseai.net

Issue: Slow image push/pull performance

Cause: DNS resolves to cloud server instead of local IP.

Solution:

# Verify /etc/hosts has local resolution
cat /etc/hosts | grep harbor
# Should show: 192.168.1.83 harbor.omniverseai.net

# If missing, add it:
echo "192.168.1.83 harbor.omniverseai.net" | sudo tee -a /etc/hosts

Issue: Cannot access Harbor web UI

Solution:

# Test HTTP access (should work)
curl -i http://192.168.1.83/api/v2.0/systeminfo

# Test HTTPS access (should work)
curl -k -i https://harbor.omniverseai.net/api/v2.0/systeminfo

# If HTTP works but HTTPS doesn't, check nginx config
docker-compose exec proxy cat /etc/nginx/nginx.conf | grep "listen 8443"

# Should see active HTTPS server block
# If commented out, edit common/config/nginx/nginx.conf and restart
docker-compose restart proxy

Security Considerations

For Development Use

This setup uses self-signed certificates, which is acceptable for:

• Local development environments
• Internal testing
• Private networks

For Production Use

Consider these improvements:

1. Use CA-signed certificates from Let's Encrypt or commercial CA
2. Change default password immediately after deployment
3. Enable LDAP/OIDC for centralized authentication
4. Configure project quotas to limit resource usage
5. Enable vulnerability scanning with Trivy
6. Set up regular backups of Harbor data

Changing Admin Password

Via Web UI:

1. Login as admin
2. Go to User Settings → Change Password

Via Database (emergency):

1. Clear password as shown in troubleshooting
2. Update harbor.yml with new password
3. Restart core service

Data Persistence

Harbor data is stored in:

/Users/brunogao/ops/data/harbor/
├── ca_download/          # CA certificates
├── database/             # PostgreSQL data
├── job_logs/             # Job service logs
├── redis/                # Redis cache
├── registry/             # Image layer storage
└── secret/               # Secrets and certificates
    └── cert/
        ├── server.crt    # SSL certificate
        └── server.key    # SSL private key

Backup Harbor:

# Stop Harbor
docker-compose down

# Backup data directory
tar czf harbor-backup-$(date +%Y%m%d).tar.gz \
  /Users/brunogao/ops/data/harbor

# Start Harbor
docker-compose up -d

Restore Harbor:

# Stop Harbor
docker-compose down

# Restore data
tar xzf harbor-backup-YYYYMMDD.tar.gz -C /

# Start Harbor
docker-compose up -d

Advanced Configuration

Enable HTTPS for Cloud Access

If you want external clients to access Harbor via cloud (85.239.233.16):

# Remove local /etc/hosts override
sudo sed -i.bak '/harbor.omniverseai.net/d' /etc/hosts

# Harbor will now be accessible via cloud nginx reverse proxy
# Cloud nginx should proxy HTTPS (443) to http://10.7.0.2:80

Note: This will increase latency for local operations as traffic routes through cloud.

Custom Storage Backend

To use S3/MinIO for image storage, edit harbor.yml:

storage_service:
  s3:
    region: us-west-1
    bucket: harbor-images
    accesskey: your-access-key
    secretkey: your-secret-key

Then regenerate configuration and restart:

docker-compose down
# Re-run prepare script if available, or manually update configs
docker-compose up -d

Project Structure

harbor/
├── common/
│   └── config/          # Generated configuration files
│       ├── core/        # Harbor core config
│       ├── nginx/       # Nginx proxy config
│       └── ...
├── docker-compose.yml   # Service definitions
├── harbor.yml           # Harbor configuration
└── README.md           # This file

/Users/brunogao/ops/data/harbor/    # Data directory
/Users/brunogao/certs/              # SSL certificates

Useful Commands Reference

# View all containers
docker-compose ps

# Follow logs from all services
docker-compose logs -f

# Restart Harbor completely
docker-compose restart

# Stop Harbor (keeps data)
docker-compose stop

# Remove Harbor (keeps data)
docker-compose down

# Remove Harbor AND data (⚠️ destructive)
docker-compose down -v

# Access PostgreSQL
docker-compose exec postgresql psql -U postgres -d registry

# Execute command in core container
docker-compose exec core env

# Check nginx configuration
docker-compose exec proxy nginx -t

# View image storage usage
du -sh /Users/brunogao/ops/data/harbor/registry

Additional Documentation

• HARBOR_CLIENT_CONFIG.md - Configure external Docker clients
• HARBOR-SETUP-GUIDE.md - Detailed setup procedures
• HARBOR-CORRECT-USAGE.md - Best practices for using Harbor
• configure-k8s-harbor.sh - K3s/Kubernetes integration script
• create-harbor-projects.sh - Bulk project creation

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review Harbor logs: docker-compose logs -f
3. Consult Harbor documentation: https://goharbor.io/docs/

License

This is a deployment configuration for Harbor. Harbor itself is licensed under Apache License 2.0.