Intro
Running a container registry is more than installing software - it is about keeping image distribution reliable, observable, and recoverable. This guide walks through the Docker Registry commands you will use daily: from verifying the environment and pulling images to inspecting manifests, cleaning up tags, and troubleshooting failures.
The target audience is developers, DevOps consultants, and technical startup teams who operate a private registry or need to interact with Docker Hub efficiently. Each section follows a practical pattern: a read-only observation, a justified change, and a command or signal that verifies the outcome.
Operational safety is the core principle. Before modifying anything, capture the current state. Use placeholders instead of real secrets in examples. Limit changes to one scoped item, and know how to recover if the expected state is not reached. The commands below use a local registry at localhost:5000 as the primary example, but the patterns apply to any Docker Registry v2 deployment.
Version and Environment Inventory
Before running any registry command, confirm what is running and how it is configured. This prevents mistakes such as pushing to the wrong registry or debugging a container that is not even in the expected state.
Start with the Docker client and daemon versions. The registry API has evolved, and some commands behave differently across versions.
docker version
Expected output includes a Client section and a Server section. Note the API version for both; mismatch between client and daemon can cause unexpected errors. For registry-specific compatibility, check the registry's own version if you control it:
curl -s http://localhost:5000/v2/ | jq .
A healthy registry returns an empty JSON object {}. If you see a connection refused error, the registry is not running or not listening on that port.
Observing Running Containers and Compose Stacks
Use docker ps with a table format to see container names, status, and published ports at a glance:
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
Example output:
NAMES STATUS PORTS
registry Up 10 minutes 0.0.0.0:5000->5000/tcp
If the registry container is missing, inspect all containers including stopped ones with docker ps -a. For Compose-based deployments, use docker compose ps to see the state of services defined in docker-compose.yml.
Logs are essential for diagnosing startup failures or runtime errors. Limit the output to the most recent lines to avoid noise:
docker logs registry --tail 100
Look for lines such as level=info msg="listening on [::]:5000" to confirm the registry started correctly. Common issues include missing storage configuration or permission errors on the data directory.
When deeper configuration is needed, docker inspect reveals mounts, networks, environment variables, and health status.
docker inspect registry --format '{{json .Mounts}}'
This outputs a JSON array of mount points. Verify that the container has a persistent volume for registry data. For example, a healthy setup might show a bind mount from /var/lib/registry on the host to /var/lib/registry inside the container.
Storage and Data Persistence
Before changing or recreating the registry container, identify where image blobs are stored. A named volume is managed by Docker and survives container recreation.
# docker-compose.yml fragment
services:
registry:
image: registry:2
volumes:
- registry_data:/var/lib/registry
volumes:
registry_data:
A bind mount maps a host directory directly:
volumes:
- /srv/registry:/var/lib/registry
Bind mounts are useful for local development or when you need direct access to the files, but they can cause permission issues if the container's UID cannot write to the host path. Named volumes are generally safer for production.
A restart test validates persistence: stop the container, recreate it, and confirm images are still available.
docker stop registry
docker start registry
# Or for Compose:
docker compose stop registry
docker compose up -d registry
curl -s http://localhost:5000/v2/_catalog
The catalog endpoint lists repositories. If it returns repositories after the restart, the data was persisted correctly. If it is empty, the registry was likely writing to the container's ephemeral filesystem.
Safe Configuration Path
Registry configuration is controlled by a YAML file, often mounted into the container at /etc/docker/registry/config.yml. Changes should be deliberate, versioned, and reversible.
Viewing the Current Configuration
Never edit a config file blindly. First, confirm the file being used and its current content. If the registry is running in a container, you can extract the configuration without modifying anything:
docker exec registry cat /etc/docker/registry/config.yml
A minimal configuration looks like this:
version: 0.1
log:
fields:
service: registry
storage:
filesystem:
rootdirectory: /var/lib/registry
http:
addr: :5000
Note the storage section: this defines where blobs are stored. Changing it without migrating data will make the registry appear empty.
Making a Scoped Change
Suppose you want to enable the delete API so that you can remove tags. By default, the registry does not allow deletions unless storage deletion is explicitly enabled. The change is two-fold: add delete: enabled: true under storage and restart the registry.
Before making the change, back up the current config file:
cp config.yml config.yml.bak.$(date +%Y%m%d)
Then edit the file, adding the relevant lines:
storage:
delete:
enabled: true
filesystem:
rootdirectory: /var/lib/registry
Restart the registry and verify the new behavior by attempting a delete via the API (covered later in "Failure Modes and Recovery"). If the change causes problems, revert to the backup and restart again.
For Compose deployments, store the config in the project directory and mount it as a file:
services:
registry:
image: registry:2
volumes:
- ./config.yml:/etc/docker/registry/config.yml:ro
Using :ro (read-only) prevents accidental writes from inside the container.
Environment Variables and Secrets
Some registry features, such as S3 storage or authentication, require credentials. Avoid putting secrets directly in the config file. Instead, use environment variables or Docker secrets.
For example, if using S3 storage, the config file can reference environment variables:
storage:
s3:
accesskey: ${S3_ACCESS_KEY}
secretkey: ${S3_SECRET_KEY}
region: us-east-1
bucket: my-registry
Then pass the variables at runtime:
docker run -d -p 5000:5000 \
-e S3_ACCESS_KEY=... \
-e S3_SECRET_KEY=... \
-v /path/to/config.yml:/etc/docker/registry/config.yml \
registry:2
Never commit real keys to version control. Use a secret manager or environment file excluded from git.
Verification and Diagnostics
After any change or during regular operations, verify the registry's health and functionality with read-only commands.
Health Endpoint
The registry v2 API does not have a dedicated health endpoint, but you can check the root endpoint:
curl -s http://localhost:5000/v2/ | jq .
Expected: {}. If you want a more robust health check, enable the health endpoint by adding to the config:
http:
addr: :5000
debug:
addr: :5001
Then you can hit http://localhost:5001/debug/health which returns {} if healthy.
Listing Repositories and Tags
To see all repositories in the registry:
curl -s http://localhost:5000/v2/_catalog | jq .
Example output:
{
"repositories": [
"myapp",
"myapp-web",
"backend"
]
}
To list tags for a specific repository:
curl -s http://localhost:5000/v2/myapp/tags/list | jq .
This returns a JSON object with a tags array, e.g., ["latest", "1.0", "1.1"].
Inspecting Manifests
Before pulling or pushing, you can inspect the manifest of an image to understand its layers and configuration.
curl -s -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
http://localhost:5000/v2/myapp/manifests/latest | jq .
The response includes schemaVersion, mediaType, config, and layers. This is useful for auditing image contents, verifying digest-based references, and debugging "manifest unknown" errors.
To get the digest of a manifest, use the Docker-Content-Digest header:
curl -sI -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
http://localhost:5000/v2/myapp/manifests/latest | grep Docker-Content-Digest
Example output:
Docker-Content-Digest: sha256:1234abcd...
This digest uniquely identifies the manifest and can be used for immutable pulls.
Docker Client Diagnostics
When working with a remote registry, the docker CLI provides several commands for troubleshooting:
docker search myapp- search Docker Hub (useful to verify network access and registry connectivity).docker pull localhost:5000/myapp:latest- pull with verbose output to see layer downloads and potential errors.docker push localhost:5000/myapp:1.1- push and observe upload progress.
For pull/push issues, set DOCKER_CONTENT_TRUST=0 if you encounter signature verification errors in a development environment (never disable trust in production).
Failure Modes and Recovery
Even with careful planning, failures happen. Recognizing common failure patterns and knowing how to recover is critical.
Manifest Unknown
Symptom: docker pull fails with manifest unknown or HTTP 404 from the registry API.
Cause: The tag no longer exists, was never pushed, or the repository name is misspelled. It can also occur if the registry's storage was wiped or changed.
Diagnosis:
curl -s http://localhost:5000/v2/myapp/tags/list
If the tag is missing, it was deleted or never pushed. Check docker images locally to see if the image exists.
Recovery: Push the image again if it exists locally:
docker tag myapp:latest localhost:5000/myapp:latest
docker push localhost:5000/myapp:latest
If the manifest is in the registry but docker pull still fails, try pulling by digest:
docker pull localhost:5000/myapp@sha256:1234abcd...
If that works, the tag may be corrupted or pointing to a missing manifest. Delete the tag and re-push.
Storage Permission Denied
Symptom: The registry container starts but the log shows permission denied when writing to /var/lib/registry.
Cause: The host directory for a bind mount is owned by a different UID than the registry process (which runs as UID 1000 by default).
Diagnosis:
docker logs registry | grep -i permission
Check ownership of the host directory:
ls -ld /srv/registry
If it is owned by root and the registry runs as non-root, writes will fail.
Recovery: Change ownership of the host directory to match the container's UID, or run the container with a user that matches. For a quick fix in development:
chown -R 1000:1000 /srv/registry
Better: define a named volume, which handles permissions automatically.
Delete Fails with 405 Method Not Allowed
Symptom: Attempting to delete a tag via the API returns HTTP 405 or an error appearing in logs.
Cause: The delete API is disabled by default. The config does not have storage.delete.enabled: true.
Diagnosis: Check the config for the delete section.
docker exec registry cat /etc/docker/registry/config.yml | grep -A2 delete
Recovery: Enable delete as described in "Safe Configuration Path", restart the registry, and retry. Note that deleting a manifest only removes the tag reference; the blobs may remain until garbage collection is run.
Garbage Collection
After deleting tags, blobs become orphaned and consume disk space. To reclaim space, run garbage collection:
docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml --dry-run
Replace --dry-run with no flag to actually delete blobs. Run this while the registry is in read-only mode or stopped to prevent corruption.
Operations Checklist
Use this checklist during routine maintenance, incident response, or before making changes.
Before Any Change
- [ ] Record the current registry version and configuration:
docker exec registry cat /etc/docker/registry/config.yml > config.backup - [ ] Verify the registry is healthy:
curl -s http://localhost:5000/v2/ - [ ] List repositories and tags to have a baseline:
curl -s http://localhost:5000/v2/_catalog - [ ] Ensure you have a rollback plan: backed-up config, known-good image tags, or a snapshot.
During the Change
- [ ] Make one change at a time (e.g., edit config, update environment variable, or recreate container).
- [ ] If editing config, use version control or keep a timestamped backup.
- [ ] Restart the registry and watch logs for errors:
docker logs registry --tail 100 -f - [ ] Test the change with a read-only command first.
After the Change
- [ ] Verify health:
curl -s http://localhost:5000/v2/ - [ ] Pull and push a test image to confirm full functionality:
docker pull hello-world
docker tag hello-world localhost:5000/test:1
docker push localhost:5000/test:1
docker rmi localhost:5000/test:1
docker pull localhost:5000/test:1
- [ ] If the test succeeds, delete the test image and tag.
- [ ] Update documentation or runbook with the new state.
Assign a single accountable owner for registry operations, such as the DevOps lead. Review the registry configuration and security settings monthly, or after any major infrastructure change.
Common Pitfalls
Several mistakes recur in registry operations. Knowing them saves time and prevents data loss.
Using latest Tag in Production
Why it happens: Convenience. Developers push latest and deployment scripts always pull it.
Risk: Non-deterministic builds, inability to roll back, and ambiguity about what is running.
Avoidance: Always tag images with explicit versions (1.0.0, commit SHA, or date). Use immutable tags where possible. Enforce via CI/CD policies.
Ignoring Storage Backend Limitations
Why it happens: The default filesystem storage is simple and works locally, so teams assume it scales.
Risk: Performance degradation, lack of redundancy, and single point of failure.
Avoidance: Evaluate object storage (S3, GCS, Azure Blob) for production. Test throughput and latency with realistic image sizes. Monitor disk usage on the registry host.
Exposing Registry Without Authentication
Why it happens: Quick setup for development, then forgotten.
Risk: Anyone can push malicious images or pull proprietary code.
Avoidance: Always enable authentication (basic auth, token auth) and TLS. Use a reverse proxy like Nginx with client certificates for sensitive environments. Regularly audit access.
Overlooking Garbage Collection
Why it happens: Deletes seem to work, so no one thinks about leftover blobs.
Risk: Disk fills up, registry becomes slow, and backups grow unnecessarily.
Avoidance: Schedule regular garbage collection after tagged deletions. Monitor disk usage and set alerts. Use --dry-run first to estimate reclaimable space.
Editing Config Without Version Control
Why it happens: Config file is inside a container or on a server without git.
Risk: No history, hard to rollback, and changes are not reviewable.
Avoidance: Keep config in a repository, deploy via automation, and use docker config or mount from host with proper permissions. Document every manual change.
Conclusion
Mastering Docker Registry commands transforms you from firefighting to proactive operation. The key is to treat the registry as a critical infrastructure component: observe before changing, limit blast radius, verify outcomes, and document recovery paths.
As a next step, choose one low-risk verification from this guide - such as listing repositories and checking manifest digests - and run it against your registry. Record the current state, compare with expectations, and if something is off, use the diagnostic patterns to investigate.
Remember that the registry is part of a larger ecosystem including Docker Hub, image tagging, and CI/CD pipelines. A reliable workflow makes failure visible, protects sensitive values, and defines recovery before an incident forces a decision.