Guidance for publishing, pulling, and managing Docker images.
When to Use
ALWAYS use this skill when the user mentions:
- "docker hub", "docker registry", "image registry"
- "docker push", "docker pull", "docker tag"
- "private registry", "private registry", "Harbor"
- "image acceleration", "registry mirror"
- "docker login", "authentication"
Core Workflow
# Login
docker login
docker login registry.example.com # Private registry
docker tag myapp:latest myuser/myapp:v1.0.0 docker tag myapp:latest myuser/myapp:latest
Pushdocker push myuser/myapp:v1.0.0 docker push myuser/myapp:latest
Pulldocker pull myuser/myapp:v1.0.0 docker pull myuser/myapp:latest
## Tag Strategy
| Tag | Purpose | Retention |
|-----|---------|-----------|
| `v1.2.3` | Exact release (semver) | Forever |
| `v1.2` | Minor version latest | Until next minor |
| `v1` | Major version latest | Until next major |
| `latest` | Latest build (dev only!) | Rolling |
| `sha256-abc123` | Digest pin | As needed |
Production: NEVER use :latest. Always pin exact version or digest. Development: :latest is OK for convenience.
## Private Registry
### Docker Registry (Official)
```bash
docker run -d -p 5000:5000 --name registry \
-v registry:/var/lib/registry \
registry:2
docker tag myapp localhost:5000/myapp:v1
docker push localhost:5000/myapp:v1
Harbor (Enterprise)
# Download and run
wget https://github.com/goharbor/harbor/releases/download/v2.10.0/harbor-offline-installer-v2.10.0.tgz
tar xzf harbor-offline-installer-v2.10.0.tgz
cd harbor
cp harbor.yml.tmpl harbor.yml
# Edit harbor.yml (hostname, passwords)
./install.sh
Image Digest (Immutable Reference)
# Get digest
docker inspect --format='{{.RepoDigests}}' myimage:tag
# Pull by digest (immutable)
docker pull alpine@sha256:abc123...
Workflow — Recommended Operation Process
Step 1: Log in to the registry: docker login or docker login ghcr.io
Step 2: Tag: docker tag myapp:v1 ghcr.io/org/myapp:v1
Step 3: Push the image: docker push ghcr.io/org/myapp:v1
Step 4: Verify: docker pull ghcr.io/org/myapp:v1 Pull to confirm
Step 5: Pin the version: For production use docker pull myapp@sha256:abc...
Gotchas — Common Pitfalls
:latestin production: Tags are mutable —latestcan point to different images over time. → Recovery: Always pin version or digest:docker pull myapp:v1.2.3@sha256:abc....- Mixed public/private registries:
docker loginis per-registry. → Recovery:docker login registry.example.comseparately; use credential helpers:docker-credential-ecr-loginfor AWS ECR. - Large image push timeout: Set
max-concurrent-uploadsin daemon config for large images. → Recovery: Edit/etc/docker/daemon.json:{"max-concurrent-uploads": 1}for slow connections. - Registry auth in CI: Use
docker/login-action(GitHub Actions) or secrets manager. → Recovery: Never commit credentials; use OIDC for cloud registries instead of long-lived tokens.
Boundary — Capability Boundaries (Applicable and Non-Applicable Scenarios)
| Category | Scenario | Description |
|---|---|---|
| ✅ Can do | Public registry use (Docker Hub/GHCR) | Login, push/pull, tag management |
| ✅ Can do | Private registry setup | Docker Registry + Harbor enterprise solution |
| ✅ Can do | Tag strategy formulation | semver/sha256/digest comparison and selection |
| ⚠️ Conditional | Image acceleration (registry-mirrors) | Requires configuring daemon.json + an available mirror service |
| ⚠️ Conditional | Harbor high-availability deployment | Requires additional configuration of Redis Cluster + PG primary-replica |
| ❌ Out of scope | Image building | Use docker-build |
| ❌ Out of scope | CVE scanning | Use docker-scout |
| ❌ Out of scope | CI/CD image management | Use docker-cicd |
When NOT to Use
| ❌ Skip | ✅ Use Instead |
|---|---|
| Building images | docker-build |
| Vulnerability scanning | docker-scout |
| CI/CD pipeline | docker-cicd |
| Docker basics | docker-basics |
Security & Stability
- Never commit registry credentials. Use CI secrets manager.
- Use content trust:
export DOCKER_CONTENT_TRUST=1for signed images. - Harbor provides vulnerability scanning, replication, and RBAC.
- No executable scripts bundled. Guidance only.
📚 Official Documentation Reference
| Documentation | Address |
|---|---|
| Docker Hub | https://docs.docker.com/docker-hub/ |
| Docker Hub API | https://docs.docker.com/reference/api/hub/latest/ |
| Docker Registry | https://docs.docker.com/registry/ |
| Harbor Project | https://goharbor.io/ |
| Image Management CLI | https://docs.docker.com/reference/cli/docker/image/ |
| Content Trust | https://docs.docker.com/engine/security/trust/ |
🧭 Docker Skills Journey
📍 You are here:
docker-hub— Image Registry Management
← Prev: docker-scout — Vulnerability scanning
→ Next: docker-cicd — CI/CD integration
FAQ
Q1: How do I quickly get started with this skill? A: Refer to the Quick Start section above and follow the steps.
Q2: What should I do if I encounter a version incompatibility issue? A: Check dependency versions, use a lock file to pin them, and refer to the Common Pitfalls section.
Q3: How do I use it in a production environment? A: Refer to the Best Practices section, ensure the configuration is correct, and implement monitoring and logging.
Q4: How can performance be optimized? A: Refer to the performance optimization documentation and use methods such as caching and indexing.
Q5: How can I contribute or provide feedback? A: Submit an Issue or Pull Request in the GitHub repository.
Q6: Is Chinese supported? A: Chinese documentation and Chinese comments are supported; see the China Adaptation section for details.