labFusion/docs/DOCKER_RATE_LIMIT_FIX.md

Docker Hub Rate Limit Fix

Problem

Error response from daemon: toomanyrequests: You have reached your unauthenticated pull rate limit. https://www.docker.com/increase-rate-limit

Docker Hub has strict rate limits:

• Unauthenticated: 100 pulls per 6 hours per IP
• Authenticated (free): 200 pulls per 6 hours per user
• Pro/Team: Higher limits

Solutions

Solution 1: Use Docker Hub Authentication (Recommended)

1.1. Create Docker Hub Account

1. Go to Docker Hub
2. Create a free account
3. Note your username and password

1.2. Update Runner Configurations

Add Docker authentication to each runner config:

runners/config_heavy.yaml:

container:
  # Docker registry authentication
  docker_username: "your_dockerhub_username"
  docker_password: "your_dockerhub_password"

runners/config_light.yaml:

container:
  # Docker registry authentication
  docker_username: "your_dockerhub_username"
  docker_password: "your_dockerhub_password"

runners/config_docker.yaml:

container:
  # Docker registry authentication
  docker_username: "your_dockerhub_username"
  docker_password: "your_dockerhub_password"

runners/config_security.yaml:

container:
  # Docker registry authentication
  docker_username: "your_dockerhub_username"
  docker_password: "your_dockerhub_password"

1.3. Alternative: Use Environment Variables

Instead of hardcoding credentials, use environment variables:

Update runners/.env.runners:

# Docker Hub credentials
DOCKER_USERNAME=your_dockerhub_username
DOCKER_PASSWORD=your_dockerhub_password

Update config files:

container:
  docker_username: ${DOCKER_USERNAME}
  docker_password: ${DOCKER_PASSWORD}

Solution 2: Use Alternative Registries

2.1. Use GitHub Container Registry (ghcr.io)

Update image references to use GitHub's registry:

Heavy Runner:

labels:
  - "java:docker://ghcr.io/openjdk/openjdk:17-jdk-slim"
  - "python:docker://ghcr.io/library/python:3.11-slim"

Light Runner:

labels:
  - "nodejs:docker://ghcr.io/library/node:20-slim"
  - "frontend:docker://ghcr.io/library/node:20-slim"

2.2. Use Quay.io Registry

labels:
  - "java:docker://quay.io/eclipse/alpine_jdk17:latest"
  - "python:docker://quay.io/python/python:3.11-slim"
  - "nodejs:docker://quay.io/node/node:20-slim"

Solution 3: Use Local Image Caching

3.1. Pre-pull Images on Runner Host

# On your runner host machine
docker pull openjdk:17-jdk-slim
docker pull python:3.11-slim
docker pull node:20-slim
docker pull docker:24-dind
docker pull alpine:3.19

# Tag as local images
docker tag openjdk:17-jdk-slim localhost:5000/openjdk:17-jdk-slim
docker tag python:3.11-slim localhost:5000/python:3.11-slim
docker tag node:20-slim localhost:5000/node:20-slim
docker tag docker:24-dind localhost:5000/docker:24-dind
docker tag alpine:3.19 localhost:5000/alpine:3.19

3.2. Update Config to Use Local Images

labels:
  - "java:docker://localhost:5000/openjdk:17-jdk-slim"
  - "python:docker://localhost:5000/python:3.11-slim"
  - "nodejs:docker://localhost:5000/node:20-slim"

Solution 4: Reduce Image Pulls

4.1. Disable Force Pull

Update all config files:

container:
  # Don't pull if image already exists
  force_pull: false

4.2. Use Image Caching

container:
  # Enable image caching
  force_pull: false
  force_rebuild: false

Solution 5: Use Self-Hosted Registry

5.1. Set up Local Registry

# Run local Docker registry
docker run -d -p 5000:5000 --name registry registry:2

# Mirror images to local registry
docker pull openjdk:17-jdk-slim
docker tag openjdk:17-jdk-slim localhost:5000/openjdk:17-jdk-slim
docker push localhost:5000/openjdk:17-jdk-slim

5.2. Update Configs to Use Local Registry

labels:
  - "java:docker://localhost:5000/openjdk:17-jdk-slim"

Recommended Approach

For immediate fix: Use Solution 1 (Docker Hub authentication) For long-term: Combine Solutions 1 + 4 (auth + caching)

Implementation Steps

1. Create Docker Hub account (if you don't have one)
2. Update .env.runners with credentials
3. Update all config files with authentication
4. Set force_pull: false to reduce pulls
5. Test with a simple job

Verification

After implementing, test with:

# Check if authentication works
docker login
docker pull openjdk:17-jdk-slim

References

• Docker Hub Rate Limits
• Gitea Actions Documentation
• Docker Registry Authentication