## 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.

```bash
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:

```bash
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:

```bash
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:

```bash
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.

```bash
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.

```yaml
# 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:

```yaml
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.

```bash
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:

```bash
docker exec registry cat /etc/docker/registry/config.yml
```

A minimal configuration looks like this:

```yaml
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:

```bash
cp config.yml config.yml.bak.$(date +%Y%m%d)
```

Then edit the file, adding the relevant lines:

```yaml
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:

```yaml
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:

```yaml
storage:
  s3:
    accesskey: ${S3_ACCESS_KEY}
    secretkey: ${S3_SECRET_KEY}
    region: us-east-1
    bucket: my-registry
```

Then pass the variables at runtime:

```bash
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:

```bash
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:

```yaml
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:

```bash
curl -s http://localhost:5000/v2/_catalog | jq .
```

Example output:

```json
{
  "repositories": [
    "myapp",
    "myapp-web",
    "backend"
  ]
}
```

To list tags for a specific repository:

```bash
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.

```bash
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:

```bash
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**:

```bash
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:

```bash
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:

```bash
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**:

```bash
docker logs registry | grep -i permission
```

Check ownership of the host directory:

```bash
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:

```bash
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.

```bash
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:

```bash
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:
  ```bash
  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.