# Docker Publishing Troubleshooting Guide

This guide helps resolve Docker Hub publishing failures and provides tools for manual intervention when the automated
release process encounters issues.

## 🚨 Current Status - Multiple Missing Versions

**Investigation Results:**

- NPM Publishing: ✅ All versions available (2.0.4, 2.1.0, 2.2.0, 2.3.0)
- Docker Hub Publishing: ❌ Multiple versions missing since v2.0.4

**Missing Docker Hub Versions:**

- v2.0.4 (original issue)
- v2.1.0, v2.2.0, v2.3.0 (subsequent failures)

**Root Cause:** Systemic Docker publishing failure in release workflow since v2.0.4 release.

**Available Versions on Docker Hub:**

- ✅ v2.0.0, v2.0.1, v2.0.2, v2.0.3 (working)
- ❌ v2.0.4, v2.1.0, v2.2.0, v2.3.0 (missing)

### Bulk Recovery Process

To resolve all missing versions at once:

```bash
# Fix all missing versions
for version in 2.0.4 2.1.0 2.2.0 2.3.0; do
  ./scripts/fix-docker-publishing.sh republish $version
  sleep 60  # Wait between publishes
done

# Verify all versions
./scripts/fix-docker-publishing.sh status
```

### Missing Docker Hub Versions

**Symptoms:**

- NPM publishing succeeds but Docker Hub fails
- Verification workflow reports missing versions
- GitHub releases exist but corresponding Docker images are absent

**Root Causes:**

- Docker Hub API rate limiting
- Network timeouts during multi-platform builds
- Docker registry authentication issues
- Temporary Docker Hub service disruptions

## 🔧 Resolution Tools

### 1. Quick Fix Script

For immediate resolution of publishing failures:

```bash
# Fix specific v2.0.4 issue (automatic)
./scripts/fix-docker-publishing.sh fix-2.0.4

# Check any version status
./scripts/fix-docker-publishing.sh check 2.1.0

# Trigger manual republish
./scripts/fix-docker-publishing.sh republish 2.0.4

# Check status of recent versions
./scripts/fix-docker-publishing.sh status
```

### 2. Manual Docker Publishing Script

For detailed control over the publishing process:

```bash
# Requires Docker credentials in environment
export DOCKER_USERNAME="your-username"
export DOCKER_PASSWORD="your-token"

# Publish missing version
./scripts/manual-docker-publish.sh 2.0.4

# Publish for specific platforms only
./scripts/manual-docker-publish.sh 2.0.4 linux/amd64
```

### 3. GitHub Workflow Manual Trigger

Using GitHub CLI or web interface:

```bash
# Using GitHub CLI
gh workflow run manual-docker-republish.yml -f version=2.0.4

# Verify only (no publishing)
gh workflow run manual-docker-republish.yml -f version=2.0.4 -f verify_only=true

# Custom platforms
gh workflow run manual-docker-republish.yml -f version=2.0.4 -f platforms=linux/amd64
```

## 🔍 Verification Process

### Automated Verification

The improved verification workflow now includes:

1. **Docker Hub API Check** - Queries the registry API
2. **Docker Pull Verification** - Attempts to pull the image
3. **Enhanced Debugging** - Shows available tags and detailed logs
4. **Multiple Tag Format Support** - Checks both `v2.0.4` and `2.0.4` formats

### Manual Verification

```bash
# Check via Docker Hub API
curl -s https://hub.docker.com/v2/repositories/docdyhr/mcp-wordpress/tags | \
  jq '.results[] | select(.name | test("2.0.4")) | {name: .name, last_updated: .last_updated}'

# Check via Docker pull
docker pull docdyhr/mcp-wordpress:2.0.4
docker pull docdyhr/mcp-wordpress:v2.0.4

# Verify image metadata
docker inspect docdyhr/mcp-wordpress:2.0.4 | jq '.[].Config.Labels'
```

## 🛠️ Workflow Improvements

### Enhanced Release Workflow

The release workflow now includes:

- **Retry Mechanism**: Automatic retry on Docker build failure
- **Immediate Verification**: Post-build image validation
- **Better Error Reporting**: Detailed failure notifications
- **Graceful Degradation**: Continue if NPM succeeds but Docker fails

### Improved Verification Workflow

- **Multi-Method Verification**: API + Docker pull validation
- **Enhanced Debugging**: Shows available tags and API responses
- **Better Issue Creation**: More detailed error reports with fix instructions
- **Retry Integration**: Automatic retry triggers for failed publishes

## 📋 Troubleshooting Checklist

### Before Manual Intervention

- [ ] Check if NPM version exists: `npm view mcp-wordpress@2.0.4`
- [ ] Verify GitHub tag exists: `git tag -l | grep v2.0.4`
- [ ] Check recent workflow runs for error patterns
- [ ] Verify Docker Hub credentials in repository secrets

### During Manual Fix

- [ ] Run verification first: `./scripts/fix-docker-publishing.sh check 2.0.4`
- [ ] Use appropriate script based on access level (local vs. GitHub Actions)
- [ ] Monitor workflow progress if using GitHub Actions
- [ ] Wait for Docker Hub propagation (30-60 seconds)

### After Resolution

- [ ] Verify via multiple methods (API, Docker pull)
- [ ] Run verification workflow: `gh workflow run verify-release.yml -f version=2.0.4`
- [ ] Update any dependent systems or documentation
- [ ] Close related GitHub issues

## 🔐 Security Considerations

### Credential Management

- **GitHub Actions**: Uses repository secrets (secure)
- **Local Scripts**: Requires environment variables (use with caution)
- **Docker Tokens**: Use Docker Hub access tokens, not passwords

### Image Integrity

All published images include:

- **Provenance**: Build attestation data
- **SBOM**: Software Bill of Materials
- **Signatures**: Cryptographic verification
- **Metadata**: Complete OCI labels

## 📈 Monitoring & Alerts

### Automated Monitoring

- **Verification Workflow**: Runs after every release
- **Issue Creation**: Automatic tickets for failures
- **Status Checks**: Integration with GitHub commit status

### Manual Monitoring

```bash
# Check recent publishing status
./scripts/fix-docker-publishing.sh status

# Monitor workflow runs
gh run list --workflow=release.yml --limit=5
gh run list --workflow=verify-release.yml --limit=5

# Check Docker Hub directly
curl -s https://hub.docker.com/v2/repositories/docdyhr/mcp-wordpress/tags | \
  jq '.results[0:5] | .[] | {name: .name, last_updated: .last_updated}'
```

## 🆘 Emergency Recovery

If all automated methods fail:

1. **Manual Docker Build:**

   ```bash
   git checkout v2.0.4
   docker buildx build --platform linux/amd64,linux/arm64 \
     --tag docdyhr/mcp-wordpress:2.0.4 \
     --tag docdyhr/mcp-wordpress:v2.0.4 \
     --push .
   ```

2. **Contact Repository Maintainer:**

   - Create detailed issue with error logs
   - Include attempted resolution steps
   - Mention urgency level and impact

3. **Fallback Options:**
   - Use previous version temporarily
   - Build local image for immediate needs
   - Use GitHub Container Registry as alternative

## 📞 Support

- **GitHub Issues**: [Create Issue](https://github.com/docdyhr/mcp-wordpress/issues/new)
- **Workflow Logs**: Check Actions tab for detailed error information
- **Docker Hub Status**: [Docker Hub Status Page](https://status.docker.com/)
