bakery-ia/docs/DOCKERHUB_SETUP.md

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:

./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:

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

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

3. Verify Pods Can Pull Images

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

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:

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:

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):

tilt up

Docker Hub Mode:

export USE_DOCKERHUB=true
export DOCKERHUB_USERNAME=uals
tilt up

3. Scripts

Two new scripts were created:

1. setup-dockerhub-secrets.sh

   • Creates Docker Hub secrets in all namespaces
   • Idempotent (safe to run multiple times)

2. 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:

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

# Login first
docker login -u uals

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

Or manually for a specific image:

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

kubectl get secret dockerhub-creds -n bakery-ia

Verify secret is correctly configured:

kubectl get secret dockerhub-creds -n bakery-ia -o yaml

Check pod events:

kubectl describe pod <pod-name> -n bakery-ia

Problem: Authentication failure

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

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

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:

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
• Security Implementation
• Tilt Development Workflow

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>