Private Docker Registry Setup Documentation
Table of Contents
- Overview
- Architecture
- Directory Structure
- Services & Components
- Configuration Files
- Reverse Proxy Configuration
- Automation Scripts
- Security & Credentials
- Monitoring & Observability
- Backup & Recovery
- Maintenance Procedures
- Troubleshooting
- Disaster Recovery
- References & Resources
Overview
This documentation covers a comprehensive private Docker registry setup running on a Debian 13 VPS. The system provides automated image synchronization from multiple public registries (Docker Hub, GHCR, LSCR, GCR, Quay), complete monitoring stack, security features, and robust operational procedures.
Key Features
- Private Docker Registry with Redis caching
- Automated Image Synchronization via regsync
- Web UI for registry management
- Complete Monitoring Stack (Prometheus + Grafana + cAdvisor)
- Security Layer with CrowdSec intrusion detection
- Automated Backups to Hetzner Storage Box
- Multi-channel Notifications (ntfy + Gotify)
- Comprehensive Automation scripts for all operations
System Requirements
- OS: Debian 13
- Docker: Latest version with Compose plugin
- Domain:
registry.my_domain.tld(with proper DNS setup) - SSL: Automatic via Caddy
- Storage: External backup to Hetzner Storage Box
Architecture
Network Architecture
Internet → Caddy (Port 443/8080) → Internal Services
├── Docker Registry (Port 5000)
├── Registry UI
├── Prometheus (Port 9090)
├── Grafana (Port 3000)
├── CrowdSec (Port 8080)
└── Portainer
Data Flow
- External requests → Caddy reverse proxy
- Image pulls/pushes → Docker Registry → Redis cache
- Monitoring data → Prometheus → Grafana dashboards
- Security events → CrowdSec → Log analysis
- Registry events → Webhook receiver → Notifications
Directory Structure
/home/user/registry/
├── caddy/ # Caddy reverse proxy
│ ├── Caddyfile # Caddy configuration
│ ├── config/ # Caddy config storage
│ ├── data/ # Caddy data (certificates)
│ └── logs/ # Access logs
├── crowdsec/ # Security monitoring
│ ├── config/ # CrowdSec configuration
│ └── data/ # CrowdSec data
├── docker-compose.yml # Main orchestration file
├── docker-registry/ # Registry core
│ ├── config.yml # Registry configuration
│ ├── config.yml.bak # Configuration backup
│ └── data/ # Registry image storage
├── grafana/ # Monitoring dashboards
│ ├── grafana-config/ # Configuration files
│ ├── grafana-data/ # Dashboard data
│ ├── grafana-logs/ # Application logs
│ └── grafana-provisioning/ # Auto-provisioning configs
├── logs/ # Centralized logging
│ ├── cron-job_logs/ # Scheduled job logs
│ └── log_archive/ # Rotated log archive
├── portainer_data/ # Container management UI
├── prometheus/ # Metrics collection
│ ├── prometheus_data/ # Time-series data
│ └── prometheus.yml # Prometheus configuration
├── redis/ # Registry caching
│ ├── config/ # Redis configuration
│ └── data/ # Cache data
├── secrets/ # Credential storage
│ ├── ghcr_token # GitHub Container Registry
│ ├── ghcr_user
│ ├── gotify_token # Gotify notifications
│ ├── gotify_url_secret
│ ├── hub_token # Docker Hub
│ ├── hub_user
│ ├── ntfy_token # ntfy notifications
│ ├── oauth2_cookie_secret # OAuth2 authentication
│ ├── oidc_client_id # OIDC configuration
│ ├── oidc_client_secret
│ ├── private_registry_identifier
│ ├── registry_host # Registry hostname
│ ├── registry_pass # Registry credentials
│ └── registry_user
├── check_changes.sh # Registry change detection
├── check_sync.sh # Regsync automation
├── manage_regsync.sh # Interactive regsync management
├── regbot.yml # Regbot configuration
├── regsync.yml # Image synchronization config
├── run_backup.sh # Backup automation
└── run_gc.sh # Garbage collection
Services & Components
Core Services (docker-compose.yml)
Registry Service
- Image:
registry:3 - Purpose: Core Docker registry following official deployment guidelines
- Resources: 1.5 CPU, 2GB RAM
- Storage: Filesystem backend with Redis caching
- Port: 5000 (internal)
- Health Check: Uses
/v2/endpoint as recommended
Caddy (Reverse Proxy)
- Image:
ghcr.io/buildplan/cs-caddy:latest - Purpose: TLS termination and reverse proxy
- Features: Automatic HTTPS, access logging
- Ports: 8080, 443
- Security: Follows registry TLS best practices
Redis (Cache Layer)
- Image:
redis:alpine - Purpose: Registry blob caching for improved performance
- Resources: 0.25 CPU, 256MB RAM
- Configuration: Custom redis.conf for registry optimization
Registry UI
- Image:
joxit/docker-registry-ui:main - Purpose: Web interface for registry browsing
- Features: Dark theme, image deletion capability
- Dependencies: Registry service
Regsync (Synchronization)
- Image:
ghcr.io/regclient/regsync:latest - Purpose: Automated image synchronization from multiple registries
- Mode: Server mode with scheduled syncing
- Resources: 0.5 CPU, 512MB RAM
- Documentation: Official regsync guide
Regbot (Registry Management)
- Image:
ghcr.io/regclient/regbot:latest - Purpose: Registry automation and management
- Resources: 0.25 CPU, 256MB RAM
Monitoring Stack
Prometheus
- Purpose: Metrics collection and storage
- Resources: 0.5 CPU, 512MB RAM
- Storage: Local time-series database
- Port: 9090
- Integration: Registry metrics endpoint enabled
Grafana
- Purpose: Metrics visualization and dashboards
- Resources: 0.5 CPU, 512MB RAM
- Authentication: Admin credentials via environment
- Port: 3000
cAdvisor
- Purpose: Container metrics collection
- Privileges: Requires privileged mode for system metrics
- Resources: 0.25 CPU, 512MB RAM
- Port: 8080
Security & Management
CrowdSec
- Purpose: Intrusion detection and prevention
- Resources: 0.5 CPU, 1GB RAM
- Integration: Caddy log analysis
- Health Check: Built-in status monitoring
Portainer
- Purpose: Docker container management UI
- Resources: 0.25 CPU, 256MB RAM
- Access: Docker socket mounted
Registry Webhook Receiver
- Purpose: Registry event notifications
- Integration: ntfy notifications
- Resources: 0.25 CPU, 128MB RAM
Configuration Files
Registry Configuration (docker-registry/config.yml)
Based on the official configuration reference, the registry is configured with:
version: 0.1
log:
level: info
formatter: text
storage:
filesystem:
rootdirectory: /var/lib/registry
delete:
enabled: true # Enables image deletion
cache:
blobdescriptor: redis # Redis caching for performance
http:
addr: :5000
secret: [REDACTED] # HTTP secret for upload coordination
debug:
addr: :5001
prometheus:
enabled: true # Metrics endpoint
path: /metrics
notifications:
events:
includereferences: true
endpoints:
- name: ntfy
disabled: false
url: https://ntfy.my_domain.tld/registry-events
headers:
Authorization: Bearer [TOKEN]
Title: Docker Registry Event
Tags: docker
timeout: 3s
threshold: 5
backoff: 5s
health:
storagedriver:
enabled: true # Storage health checks
interval: 10s
threshold: 3
redis:
addrs: ["redis:6379"]
db: 0
# Connection pool settings optimized for registry caching
Key Security Features:
- TLS termination handled by Caddy proxy
- Basic authentication for push operations
- Redis caching for improved performance
- Webhook notifications for registry events
- Health checks for storage driver
Regsync Configuration (regsync.yml)
Following regsync best practices, the configuration includes:
- Version: 1
- Sync Interval: 12 hours (prevents upstream rate limiting)
- Parallelism: 1 (sequential processing for stability)
- Registries: 120+ image synchronizations
- Source Registries:
- Docker Hub (with authentication)
- GitHub Container Registry (GHCR)
- LinuxServer.io Container Registry (LSCR)
- Google Container Registry (GCR)
- Quay.io
- Codeberg.org
- Authentication: File-based credentials for authenticated registries
- Tag Filtering: Smart regex patterns for version control
Log Rotation (/etc/logrotate.d/private-registry-logs)
/home/user/registry/logs/*.log /home/user/registry/logs/cron-job_logs/*.log {
daily
rotate 3
compress
delaycompress
missingok
notifempty
create 0644 user user
su user user
dateext
dateformat -%Y%m%d
olddir /home/user/registry/logs/log_archive
}
Reverse Proxy Configuration
Your infrastructure uses Caddy as the reverse proxy and TLS terminator, with built-in CrowdSec support for application-layer protection. You maintain a custom Caddy image in your GitHub repository:
- Custom Caddy Image: https://github.com/buildplan/cs-caddy
This image is based on the official Caddy image and includes the caddy-crowdsec bouncer plugin.
Caddyfile Breakdown
# --- Global options ---
{
email letse@my_domain.tld
admin :2019
metrics
log {
output file /var/log/caddy/access.log {
roll_size 10mb
roll_keep 5
roll_keep_for 360h
}
format json
level INFO
}
crowdsec {
api_url http://crowdsec:8080
api_key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ticker_interval 15s
appsec_url http://crowdsec:7422
}
}
# --- Registry API Block ---
registry.my_domain.tld {
route {
basic_auth {
user $2a$14$... # Pull password hash
serve_push $2a$16$... # Push password hash
}
header {
Strict-Transport-Security "max-age=31536000;"
X-Frame-Options "DENY"
X-Content-Type-Options "nosniff"
...
}
reverse_proxy registry:5000 {
transport http {
dial_timeout 5s
response_header_timeout 5m
}
}
}
}
# Additional blocks for UI, Portainer, Prometheus, Grafana, etc.
Key Points:
- Global Options: TLS cert management, metrics endpoint, admin API
- Logging: JSON logs with file rotation
- CrowdSec Integration: Built-in plugin for request filtering
- Basic Auth: Protects registry endpoints with bcrypt hashes
- Security Headers: HSTS, CSP, X-Frame-Options, and more
- Reverse Proxy: Routes subdomains to internal service ports
Subdomain Routing
registry.my_domain.tld→ Docker Registry APIui.registry.my_domain.tld→ Registry UIport.registry.my_domain.tld→ Portainerprom.registry.my_domain.tld→ Prometheusstats.registry.my_domain.tld→ Grafana (OIDC)
Best Practices
- Use strong bcrypt hashed credentials for all protected endpoints
- Configure CSP and other headers per OWASP recommendations
- Enable CrowdSec for dynamic IP banning and application security
- Keep TLS configs up to date following Let’s Encrypt best practices
Automation Scripts
check_sync.sh - Regsync Automation
Purpose: Automated image synchronization with state management
Source: GitHub Repository
Key Features:
- State-aware execution (6-hour minimum interval)
- Comprehensive error handling with
set -eandset -o pipefail - ntfy notifications for all outcomes
- Detailed logging with color-coded output
- Robust image summary parsing (improved version available)
Execution Flow:
- Check minimum interval requirement via state file
- Run regsync check command to detect needed updates
- If updates needed, execute sync operation
- Send notifications based on results
- Update state file with timestamp
Usage:
./check_sync.sh
Cron Integration:
# Add to crontab for automated execution
0 */6 * * * /home/user/registry/check_sync.sh
run_backup.sh - Backup Automation
Purpose: Consistent backup to Hetzner Storage Box
Source: GitHub Repository
Key Features:
- Service coordination (stops registry during backup for consistency)
- SSH key authentication to Hetzner Storage Box
- Gotify notifications for backup status
- Graceful service recovery regardless of backup outcome
- Complete project directory synchronization
Backup Process:
- Stop registry service for data consistency
- rsync entire project directory to Hetzner Storage Box
- Restart registry service
- Send success/failure notifications with details
Usage:
# Manual execution (requires sudo for stopping services)
sudo ./run_backup.sh
# Scheduled execution via cron
0 2 * * * /home/user/registry/run_backup.sh
run_gc.sh - Garbage Collection
Purpose: Registry cleanup and space management
Source: GitHub Repository
Process:
- Stop registry service to prevent writes during GC
- Run garbage collection with
--delete-untaggedflag - Restart registry service
- Report results via ntfy with deletion statistics
Usage:
./run_gc.sh
check_changes.sh - Change Detection
Purpose: Monitor registry content changes
Source: GitHub Repository
Features:
- Uses regctl for repository listing
- Diff-based change detection between runs
- Formatted notifications with change details
- State file management for persistent tracking
manage_regsync.sh - Interactive Management
Purpose: User-friendly regsync configuration management
Source: GitHub Repository
Features:
- Interactive menu system with color-coded output
- Add/Edit/Delete sync entries with validation
- Search functionality across sync entries
- Dry-run mode for testing changes
- Automatic backups before configuration changes
- Table-formatted display with proper text wrapping
Usage:
# Interactive mode
./manage_regsync.sh
# Dry-run mode (preview changes without applying)
./manage_regsync.sh --dry-run
Security & Credentials
Credential Management
All sensitive credentials are stored in the secrets/ directory with proper file permissions (600). The system uses file-based credential loading to avoid exposing secrets in configuration files or environment variables, following Docker security best practices.
Security Layers
- TLS Encryption: Automatic HTTPS via Caddy with Let’s Encrypt
- Intrusion Detection: CrowdSec monitoring and analysis
- Access Control: Registry authentication for push operations
- Network Isolation: Docker bridge network segmentation
- Resource Limits: Container resource constraints to prevent resource exhaustion
- Credential Separation: External secret file management
Authentication Flow
- Pull Operations: Anonymous access allowed for efficiency
- Push Operations: Authenticated via registry credentials
- UI Access: Protected by reverse proxy configuration
- Monitoring Access: Internal network only
Security Configuration Compliance:
- Follows official registry authentication guidelines
- Implements production deployment security
- Uses bcrypt password hashing for htpasswd authentication
Monitoring & Observability
Metrics Collection
- Registry Metrics: Native Prometheus endpoint (
/debug/metricson port 5001) - Container Metrics: cAdvisor collection for all services with resource usage monitoring
- System Metrics: Host-level monitoring via cAdvisor (CPU, memory, network, disk I/O)
- Security Metrics: CrowdSec Prometheus endpoint (
/metricson port 6060) - Proxy Metrics: Caddy metrics endpoint for HTTP traffic analysis
- Application Metrics: Service-specific exporters for detailed performance insights
Security Monitoring (CrowdSec)
- Threat Detection: Real-time analysis of access logs and system events
- IP Banning: Automatic blocking of malicious IPs with decision tracking
- Scenario Monitoring: Tracking of security scenario triggers and overflows
- Parser Analytics: Success/failure rates of log parsing by source
- API Metrics: Local API performance and bouncer request statistics
Key CrowdSec Metrics:
cs_active_decisions: Currently active bans and security decisionscs_alerts: Total security alerts triggered by scenarioscs_bucket_overflowed_total: Security scenarios that have triggered actionscs_lapi_decisions_ok_total: Successful bouncer API requestscs_node_hits_total: Log processing statistics by parser and sourcecs_info: CrowdSec version and configuration information
Notification Channels
- ntfy: Primary notification system
- Registry events (push/pull/delete operations)
- Regsync status updates and sync completion
- System alerts and service failures
- Garbage collection reports
- Registry change detection notifications
- Gotify: Secondary notification system
- Backup status reports with detailed logs
- Configuration changes and manual operations
- Regsync configuration management notifications
- Registry Webhooks: Built-in event notifications
- Image push/pull events with metadata
- Repository creation and deletion
- Manifest uploads and tag operations
Dashboard Access
- Grafana (Monitoring):
stats.registry.my_domain.tld- Registry performance dashboards
- Container resource monitoring
- CrowdSec security insights and threat analysis
- System performance metrics and alerting
- Prometheus (Metrics):
prom.registry.my_domain.tld- Raw metrics access and PromQL queries
- Target status and scraping health
- Alert rule configuration and testing
- Registry UI:
ui.registry.my_domain.tld- Image repository browsing
- Tag management and deletion
- Storage usage visualization
- Portainer (Container Management):
port.registry.my_domain.tld- Container lifecycle management
- Log streaming and debugging
- Resource usage monitoring
Grafana Dashboards
- Registry Performance Dashboard
- Image pull/push metrics and response times
- Storage usage and growth trends
- Cache hit rates and Redis performance
- Container Monitoring Dashboard
- Resource usage by service (CPU, memory, network)
- Container health status and restart counts
- Docker daemon metrics and performance
- CrowdSec Security Dashboard (Dashboard IDs: 19011, 19012)
- CrowdSec Insights: High-level security overview
- Active bans and security decisions
- Threat geography and attack patterns
- Scenario trigger rates and effectiveness
- CrowdSec Details: Detailed engine metrics
- Log parsing success/failure rates by source
- API performance and bouncer statistics
- Parser hit counts and error analysis
- CrowdSec Insights: High-level security overview
- System Overview Dashboard
- Host system metrics and resource utilization
- Network traffic patterns and bandwidth usage
- Disk I/O performance and storage capacity
Alerting Configuration
- High Priority Alerts: Service failures, security breaches, backup failures
- Medium Priority Alerts: Resource threshold warnings, sync failures
- Low Priority Alerts: Maintenance notifications, configuration changes
- Alert Routing: Critical alerts via both ntfy and Gotify for redundancy
Monitoring Best Practices
- Metrics Retention: Prometheus configured with appropriate retention policies
- Dashboard Refresh: Auto-refresh intervals optimized for real-time monitoring
- Alert Thresholds: Tuned based on baseline performance metrics
- Security Monitoring: CrowdSec scenarios regularly updated with threat intelligence
Backup & Recovery
Backup Strategy
- Frequency: Daily automated backups at 2 AM
- Destination: Hetzner Storage Box (reliable cloud storage)
- Method: rsync with SSH key authentication
- Scope: Complete
/home/user/registrydirectory - Consistency: Registry service stopped during backup to ensure data integrity
Backup Components
- Registry image data and metadata
- Configuration files and secrets
- Monitoring data and dashboards
- Log files and archives
- Application state and databases
Recovery Procedures
- Complete System Recovery:
# Restore from Hetzner backup rsync -avz --delete -e "ssh -p 23 -i ~/.ssh/id_hetzner_backup" \ [email protected]:home/private-registry/ \ /home/user/registry/ # Restore permissions chown -R user:user /home/user/registry chmod -R 755 /home/user/registry chmod 600 /home/user/registry/secrets/* # Start services cd /home/user/registry docker compose up -d - Selective Recovery:
- Individual service data restoration
- Configuration rollback using .bak files
- Secret file recovery from backup
Maintenance Procedures
Regular Maintenance Tasks
Daily
- Monitor notification channels for alerts
- Review backup success notifications
- Check system resource usage via Grafana
Weekly
- Review Grafana dashboards for performance trends
- Check log rotation and archive sizes
- Verify sync operations are functioning correctly
- Update synchronized image list if needed
Monthly
- Run manual garbage collection if needed
- Review and update synchronized images
- Security update check for all containers
- Backup verification test
- Review and rotate credentials
Image Management
- Adding New Images:
./manage_regsync.sh # Select: Add Sync Entry # Follow interactive prompts - Updating Sync Configuration:
# Edit existing entries ./manage_regsync.sh # Select: Edit Sync Entry - Removing Unused Images:
# Manual cleanup via UI or API # Followed by garbage collection ./run_gc.sh
System Updates
- Container Updates:
cd /home/user/registry docker compose pull docker compose up -d - Configuration Updates:
- Always backup before changes using the built-in backup functions
- Test in dry-run mode where possible
- Verify services after updates
Troubleshooting
Common Issues
Registry Not Accessible
Symptoms: Cannot access registry web UI or API Troubleshooting Steps:
- Check Caddy status and logs:
docker compose logs caddy - Verify DNS configuration and SSL certificate status
- Check firewall rules and port accessibility
- Verify registry service health:
curl -I https://registry.my_domain.tld/v2/
Sync Failures
Symptoms: Images not updating, sync errors in logs Troubleshooting Steps:
- Check regsync logs:
docker compose logs regsync - Verify credentials in secrets directory
- Test network connectivity to source registries
- Check disk space availability
- Review rate limiting issues
Backup Failures
Symptoms: Backup notifications showing failures Troubleshooting Steps:
- Verify SSH key permissions and accessibility
- Check Hetzner Storage Box connectivity:
ssh -p 23 -i ~/.ssh/id_hetzner_backup [email protected] - Verify rsync command parameters
- Check disk space on both source and destination
Performance Issues
Symptoms: Slow image pulls, high resource usage Troubleshooting Steps:
- Monitor resource usage via Grafana dashboards
- Check Redis cache hit rates and performance
- Verify disk I/O performance
- Review container resource limits
- Check for network bottlenecks
Log Locations
- Application Logs:
/home/user/registry/logs/ - Container Logs:
docker compose logs [service] - System Logs:
/var/log/(via CrowdSec integration) - Archived Logs:
/home/user/registry/logs/log_archive/
Diagnostic Commands
# Service status overview
docker compose ps
# Resource usage monitoring
docker stats
# Registry API health check
curl -s https://registry.my_domain.tld/v2/_catalog
# Regsync version and status
docker compose exec regsync regsync -c /config/regsync.yml version
# Check disk usage
df -h /home/user/registry/
# Network connectivity test
docker compose exec regsync ping docker.io
# Redis cache status
docker compose exec redis redis-cli info
Disaster Recovery
Complete System Failure
- Prepare New System:
- Install Docker and Docker Compose
- Configure user account and SSH keys
- Set up network and firewall rules
- Restore Data:
# Create directory structure mkdir -p /home/user/registry # Restore from backup rsync -avz -e "ssh -p 23 -i ~/.ssh/id_hetzner_backup" \ [email protected]:home/private-registry/ \ /home/user/registry/ - Restore Services:
cd /home/user/registry # Pull latest images docker compose pull # Start all services docker compose up -d - Verification:
- Test registry accessibility
- Verify all services are running healthy
- Check monitoring dashboards
- Test image pull/push operations
- Verify backup and sync operations
Partial Recovery Scenarios
- Configuration corruption: Restore from .bak files or backup
- Data loss: Selective restore from Hetzner backup
- Service failure: Container restart or image rebuild
- Network issues: DNS/firewall reconfiguration
- Certificate issues: Caddy certificate regeneration
Recovery Time Objectives
- RTO (Recovery Time Objective): 4 hours for complete system recovery
- RPO (Recovery Point Objective): 24 hours (daily backup frequency)
- Service Availability: 99.5% target uptime
- Data Retention: 3 days of rotated logs, indefinite backup retention
References & Resources
Official Documentation
- Docker Registry Deployment Guide: https://distribution.github.io/distribution/about/deploying/
- Registry Configuration Reference: https://distribution.github.io/distribution/about/configuration/
- Registry Authentication: https://distribution.github.io/distribution/spec/auth/token/
- Regsync Documentation: https://regclient.org/usage/regsync/
- Regclient FAQ: https://regclient.org/usage/faq/
Security Resources
- Registry Security Best Practices: https://distribution.github.io/distribution/about/deploying/#access-restrictions
- Testing Insecure Registries: https://distribution.github.io/distribution/about/insecure/
- Container Registry Best Practices: https://learn.microsoft.com/en-us/azure/container-registry/container-registry-best-practices
Monitoring & Observability
- Docker Monitoring with Prometheus: https://last9.io/blog/docker-monitoring-with-prometheus-a-step-by-step-guide/
- Grafana Docker Compose Setup: https://grafana.com/docs/grafana-cloud/send-data/metrics/metrics-prometheus/prometheus-config-examples/docker-compose-linux/
- CorwdSec Dashboard with with Prometheus/Grafana: https://docs.crowdsec.net/docs/observability/prometheus/
Proxy and Load Balancing
- Nginx Authentication Proxy: https://distribution.github.io/distribution/recipes/nginx/
- Registry with systemd: https://distribution.github.io/distribution/recipes/systemd/
Community Resources
- Registry GitHub Issues: https://github.com/distribution/distribution/issues
- Regclient Package Documentation: https://pkg.go.dev/github.com/regclient/regclient
- Chainguard Regsync Image: https://images.chainguard.dev/directory/image/regclient-regsync/overview
Source Code
- Main Scripts Repository: https://github.com/buildplan/docker/tree/main/private-registry-stack
- Sync Automation Script: https://github.com/buildplan/docker/raw/refs/heads/main/private-registry-stack/check_sync.sh
- Backup Script: https://github.com/buildplan/docker/raw/refs/heads/main/private-registry-stack/run_backup.sh
- Garbage Cleaning Script: https://github.com/buildplan/docker/raw/refs/heads/main/private-registry-stack/run_gc.sh
- Check Registry Changes Script: https://github.com/buildplan/docker/raw/refs/heads/main/private-registry-stack/check_changes.sh
Troubleshooting Resources
- Registry Health Checks: https://github.com/distribution/distribution/issues/629
- Token Authentication Issues: https://github.com/distribution/distribution/issues/3290
- JWKS Configuration: https://github.com/distribution/distribution/issues/4470
Conclusion
This private Docker registry setup represents a production-ready, enterprise-grade solution with comprehensive automation, monitoring, security, and operational procedures. The system is designed for reliability, maintainability, and scalability while providing complete visibility into all operations through extensive logging and notification systems.
The implementation follows official Docker registry deployment guidelines and incorporates industry best practices for container registry management. The comprehensive automation ensures minimal manual intervention while maintaining high availability and data integrity.
Regular maintenance following the procedures outlined in this documentation will ensure optimal performance and reliability of the registry infrastructure. The extensive monitoring and notification systems provide early warning of potential issues, enabling proactive maintenance and rapid issue resolution.
Documentation last updated: August 23, 2025
Based on: Docker Registry v3, Debian 13, Docker Compose