# Docker Hub Configuration Guide

This guide explains how to configure Docker Hub for all image pulls in the Bakery IA project.

## Overview

The project has been configured to use Docker Hub credentials for pulling both:
- **Base images** (postgres, redis, python, node, nginx, etc.)
- **Custom bakery images** (bakery/auth-service, bakery/gateway, etc.)

## Quick Start

### 1. Create Docker Hub Secret in Kubernetes

Run the automated setup script:

```bash
./infrastructure/kubernetes/setup-dockerhub-secrets.sh
```

This script will:
- Create the `dockerhub-creds` secret in all namespaces (bakery-ia, bakery-ia-dev, bakery-ia-prod, default)
- Use the credentials: `uals` / `dckr_pat_zzEY5Q58x1S0puraIoKEtbpue3A`

### 2. Apply Updated Kubernetes Manifests

All manifests have been updated with `imagePullSecrets`. Apply them:

```bash
# For development
kubectl apply -k infrastructure/kubernetes/overlays/dev

# For production
kubectl apply -k infrastructure/kubernetes/overlays/prod
```

### 3. Verify Pods Can Pull Images

```bash
# Check pod status
kubectl get pods -n bakery-ia

# Check events for image pull status
kubectl get events -n bakery-ia --sort-by='.lastTimestamp'

# Describe a specific pod to see image pull details
kubectl describe pod <pod-name> -n bakery-ia
```

## Manual Setup

If you prefer to create the secret manually:

```bash
kubectl create secret docker-registry dockerhub-creds \
  --docker-server=docker.io \
  --docker-username=uals \
  --docker-password=dckr_pat_zzEY5Q58x1S0puraIoKEtbpue3A \
  --docker-email=ualfaro@gmail.com \
  -n bakery-ia
```

Repeat for other namespaces:
```bash
kubectl create secret docker-registry dockerhub-creds \
  --docker-server=docker.io \
  --docker-username=uals \
  --docker-password=dckr_pat_zzEY5Q58x1S0puraIoKEtbpue3A \
  --docker-email=ualfaro@gmail.com \
  -n bakery-ia-dev

kubectl create secret docker-registry dockerhub-creds \
  --docker-server=docker.io \
  --docker-username=uals \
  --docker-password=dckr_pat_zzEY5Q58x1S0puraIoKEtbpue3A \
  --docker-email=ualfaro@gmail.com \
  -n bakery-ia-prod
```

## What Was Changed

### 1. Kubernetes Manifests (47 files updated)

All deployments, jobs, and cronjobs now include `imagePullSecrets`:

```yaml
spec:
  template:
    spec:
      imagePullSecrets:
      - name: dockerhub-creds
      containers:
      - name: ...
```

**Files Updated:**
- **19 Service Deployments**: All microservices (auth, tenant, forecasting, etc.)
- **21 Database Deployments**: All PostgreSQL instances, Redis, RabbitMQ
- **21 Migration Jobs**: All database migration jobs
- **2 CronJobs**: demo-cleanup, external-data-rotation
- **2 Standalone Jobs**: external-data-init, nominatim-init
- **1 Worker Deployment**: demo-cleanup-worker

### 2. Tiltfile Configuration

The Tiltfile now supports both local registry and Docker Hub:

**Default (Local Registry):**
```bash
tilt up
```

**Docker Hub Mode:**
```bash
export USE_DOCKERHUB=true
export DOCKERHUB_USERNAME=uals
tilt up
```

### 3. Scripts

Two new scripts were created:

1. **[setup-dockerhub-secrets.sh](../infrastructure/kubernetes/setup-dockerhub-secrets.sh)**
   - Creates Docker Hub secrets in all namespaces
   - Idempotent (safe to run multiple times)

2. **[add-image-pull-secrets.sh](../infrastructure/kubernetes/add-image-pull-secrets.sh)**
   - Adds `imagePullSecrets` to all Kubernetes manifests
   - Already run (no need to run again unless adding new manifests)

## Using Docker Hub with Tilt

To use Docker Hub for development with Tilt:

```bash
# Login to Docker Hub first
docker login -u uals

# Enable Docker Hub mode
export USE_DOCKERHUB=true
export DOCKERHUB_USERNAME=uals

# Start Tilt
tilt up
```

This will:
- Build images locally
- Tag them as `docker.io/uals/<image-name>`
- Push them to Docker Hub
- Deploy to Kubernetes with imagePullSecrets

## Images Configuration

### Base Images (from Docker Hub)

These images are pulled from Docker Hub's public registry:

- `python:3.11-slim` - Python base for all microservices
- `node:18-alpine` - Node.js for frontend builder
- `nginx:1.25-alpine` - Nginx for frontend production
- `postgres:17-alpine` - PostgreSQL databases
- `redis:7.4-alpine` - Redis cache
- `rabbitmq:4.1-management-alpine` - RabbitMQ message broker
- `busybox:latest` - Utility container
- `curlimages/curl:latest` - Curl utility
- `mediagis/nominatim:4.4` - Geolocation service

### Custom Images (bakery/*)

These images are built by the project:

**Infrastructure:**
- `bakery/gateway`
- `bakery/dashboard`

**Core Services:**
- `bakery/auth-service`
- `bakery/tenant-service`

**Data & Analytics:**
- `bakery/training-service`
- `bakery/forecasting-service`
- `bakery/ai-insights-service`

**Operations:**
- `bakery/sales-service`
- `bakery/inventory-service`
- `bakery/production-service`
- `bakery/procurement-service`
- `bakery/distribution-service`

**Supporting:**
- `bakery/recipes-service`
- `bakery/suppliers-service`
- `bakery/pos-service`
- `bakery/orders-service`
- `bakery/external-service`

**Platform:**
- `bakery/notification-service`
- `bakery/alert-processor`
- `bakery/orchestrator-service`

**Demo:**
- `bakery/demo-session-service`

## Pushing Custom Images to Docker Hub

Use the existing tag-and-push script:

```bash
# Login first
docker login -u uals

# Tag and push all images
./scripts/tag-and-push-images.sh
```

Or manually for a specific image:

```bash
# Build
docker build -t bakery/auth-service:latest -f services/auth/Dockerfile .

# Tag for Docker Hub
docker tag bakery/auth-service:latest uals/bakery-auth-service:latest

# Push
docker push uals/bakery-auth-service:latest
```

## Troubleshooting

### Problem: ImagePullBackOff error

Check if the secret exists:
```bash
kubectl get secret dockerhub-creds -n bakery-ia
```

Verify secret is correctly configured:
```bash
kubectl get secret dockerhub-creds -n bakery-ia -o yaml
```

Check pod events:
```bash
kubectl describe pod <pod-name> -n bakery-ia
```

### Problem: Authentication failure

The Docker Hub credentials might be incorrect or expired. Update the secret:

```bash
# Delete old secret
kubectl delete secret dockerhub-creds -n bakery-ia

# Create new secret with updated credentials
kubectl create secret docker-registry dockerhub-creds \
  --docker-server=docker.io \
  --docker-username=<your-username> \
  --docker-password=<your-token> \
  --docker-email=<your-email> \
  -n bakery-ia
```

### Problem: Pod still using old credentials

Restart the pod to pick up the new secret:

```bash
kubectl rollout restart deployment/<deployment-name> -n bakery-ia
```

## Security Best Practices

1. **Use Docker Hub Access Tokens** (not passwords)
   - Create at: https://hub.docker.com/settings/security
   - Set appropriate permissions (Read-only for pulls)

2. **Rotate Credentials Regularly**
   - Update the secret every 90 days
   - Use the setup script for consistent updates

3. **Limit Secret Access**
   - Only grant access to necessary namespaces
   - Use RBAC to control who can read secrets

4. **Monitor Usage**
   - Check Docker Hub pull rate limits
   - Monitor for unauthorized access

## Rate Limits

Docker Hub has rate limits for image pulls:

- **Anonymous users**: 100 pulls per 6 hours per IP
- **Authenticated users**: 200 pulls per 6 hours
- **Pro/Team**: Unlimited

Using authentication (imagePullSecrets) ensures you get the authenticated user rate limit.

## Environment Variables

For CI/CD or automated deployments, use these environment variables:

```bash
export DOCKER_USERNAME=uals
export DOCKER_PASSWORD=dckr_pat_zzEY5Q58x1S0puraIoKEtbpue3A
export DOCKER_EMAIL=ualfaro@gmail.com
```

## Next Steps

1. ✅ Docker Hub secret created in all namespaces
2. ✅ All Kubernetes manifests updated with imagePullSecrets
3. ✅ Tiltfile configured for optional Docker Hub usage
4. 🔄 Apply manifests to your cluster
5. 🔄 Verify pods can pull images successfully

## Related Documentation

- [Kubernetes Setup Guide](./KUBERNETES_SETUP.md)
- [Security Implementation](./SECURITY_IMPLEMENTATION_COMPLETE.md)
- [Tilt Development Workflow](../Tiltfile)

## Support

If you encounter issues:

1. Check the troubleshooting section above
2. Verify Docker Hub credentials at: https://hub.docker.com/settings/security
3. Check Kubernetes events: `kubectl get events -A --sort-by='.lastTimestamp'`
4. Review pod logs: `kubectl logs -n bakery-ia <pod-name>`