Foreman/Katello Repository Setup Guide

katello-repository-setup.md

Katello Repository Setup Script

This document contains executable hammer commands to create and sync repositories in Foreman/Katello.

Prerequisites

• Foreman/Katello server installed and running
• Hammer CLI configured with admin credentials
• Internet connectivity for repository synchronization

Configuration

First, ensure hammer is configured with proper credentials. Update the configuration file:

# Update hammer credentials in ~/.hammer/cli.modules.d/foreman.yml
cat > ~/.hammer/cli.modules.d/foreman.yml << 'EOF'
:foreman:
  :username: 'admin'
  :password: 'changeme'
EOF

Verify Organization

# List organizations
hammer organization list

Expected output: You should see "Default Organization" with ID 1.

Create Products and Repositories

1. CentOS Stream 9 Product

Create a product for CentOS Stream 9 with BaseOS and AppStream repositories:

# Create CentOS Stream 9 product
hammer product create \
  --name "CentOS Stream 9" \
  --organization "Default Organization" \
  --description "CentOS Stream 9 repositories"

# Create BaseOS repository
hammer repository create \
  --name "BaseOS" \
  --product "CentOS Stream 9" \
  --organization "Default Organization" \
  --content-type "yum" \
  --url "http://mirror.stream.centos.org/9-stream/BaseOS/x86_64/os/" \
  --download-policy "on_demand"

# Create AppStream repository
hammer repository create \
  --name "AppStream" \
  --product "CentOS Stream 9" \
  --organization "Default Organization" \
  --content-type "yum" \
  --url "http://mirror.stream.centos.org/9-stream/AppStream/x86_64/os/" \
  --download-policy "on_demand"

2. Test Repository Product

Create a test product with a small YUM repository:

# Create Test Repo product
hammer product create \
  --name "Test Repo" \
  --organization "Default Organization" \
  --description "Test YUM repository"

# Create Pteradactyl test repository
hammer repository create \
  --name "Pteradactyl" \
  --product "Test Repo" \
  --organization "Default Organization" \
  --content-type "yum" \
  --url "https://partha.fedorapeople.org/test-repos/pteradactyl/" \
  --download-policy "immediate"

3. Docker Product

Create a Docker product with container repositories:

# Create Docker product
hammer product create \
  --name "Docker" \
  --organization "Default Organization" \
  --description "Docker container images"

# Create Busybox repository (latest tag only)
hammer repository create \
  --name "Busybox" \
  --product "Docker" \
  --organization "Default Organization" \
  --content-type "docker" \
  --url "https://registry-1.docker.io" \
  --docker-upstream-name "library/busybox" \
  --include-tags "latest"

# Create Alpine repository (latest tag only)
hammer repository create \
  --name "Alpine" \
  --product "Docker" \
  --organization "Default Organization" \
  --content-type "docker" \
  --url "https://registry-1.docker.io" \
  --docker-upstream-name "library/alpine" \
  --include-tags "latest"

List All Repositories

# Verify all repositories were created
hammer repository list --organization "Default Organization"

Expected repositories:

• CentOS Stream 9 / BaseOS
• CentOS Stream 9 / AppStream
• Test Repo / Pteradactyl
• Docker / Busybox
• Docker / Alpine

Synchronize Repositories

Sync all repositories to download content:

# Sync Pteradactyl test repository (small, quick sync)
hammer repository synchronize \
  --name "Pteradactyl" \
  --product "Test Repo" \
  --organization "Default Organization" \
  --async

# Sync CentOS Stream 9 BaseOS (metadata only with on_demand policy)
hammer repository synchronize \
  --name "BaseOS" \
  --product "CentOS Stream 9" \
  --organization "Default Organization" \
  --async

# Sync CentOS Stream 9 AppStream (metadata only with on_demand policy)
hammer repository synchronize \
  --name "AppStream" \
  --product "CentOS Stream 9" \
  --organization "Default Organization" \
  --async

# Sync Docker Busybox (may fail due to Docker Hub rate limiting)
hammer repository synchronize \
  --name "Busybox" \
  --product "Docker" \
  --organization "Default Organization" \
  --async

# Sync Docker Alpine (may fail due to Docker Hub rate limiting)
hammer repository synchronize \
  --name "Alpine" \
  --product "Docker" \
  --organization "Default Organization" \
  --async

Monitor Sync Progress

# Check sync task status
hammer task list --search "label = Actions::Katello::Repository::Sync"

# Get detailed info about a specific repository
hammer repository info \
  --name "Pteradactyl" \
  --product "Test Repo" \
  --organization "Default Organization"

Troubleshooting

Docker Hub Rate Limiting

Docker Hub imposes rate limits on anonymous pulls. If you see "429 Too Many Requests" errors:

1. Option 1: Create a Docker Hub account and configure credentials in Katello
2. Option 2: Wait and retry the sync later
3. Option 3: Use alternative container registries (quay.io, gcr.io, etc.)

To add Docker Hub credentials:

hammer repository update \
  --name "Busybox" \
  --product "Docker" \
  --organization "Default Organization" \
  --username "YOUR_DOCKERHUB_USERNAME" \
  --password "YOUR_DOCKERHUB_PASSWORD"

Slow CentOS Stream Syncs

The CentOS Stream repositories contain large amounts of metadata. Even with on_demand download policy:

• BaseOS sync: 3-5 minutes
• AppStream sync: 3-5 minutes

This is normal. The sync downloads metadata but not package content until needed.

Check Sync Errors

# View detailed task output for errors
hammer task info --id TASK_ID

Verification

After syncing, verify repositories have content:

# List all products and their sync states
hammer product list --organization "Default Organization"

# Check package count for YUM repositories
hammer package list \
  --repository "Pteradactyl" \
  --product "Test Repo" \
  --organization "Default Organization"

# Check container image tags
hammer docker tag list \
  --repository "Busybox" \
  --product "Docker" \
  --organization "Default Organization"

Summary

This script creates:

• 3 Products: CentOS Stream 9, Test Repo, Docker
• 5 Repositories:
  • 2 YUM repos (CentOS BaseOS, AppStream) with on_demand policy
  • 1 YUM test repo (Pteradactyl) with immediate download
  • 2 Docker repos (Busybox, Alpine) with latest tags only

Total expected sync time: 5-10 minutes depending on network speed and server load.

Clean Up (Optional)

To remove all created repositories and products:

# Delete products (this also deletes associated repositories)
hammer product delete --name "CentOS Stream 9" --organization "Default Organization"
hammer product delete --name "Test Repo" --organization "Default Organization"
hammer product delete --name "Docker" --organization "Default Organization"

---

Generated: 2026-05-12
Foreman/Katello Version: Compatible with Katello 4.x+
Hammer CLI Version: 3.19.0+