akanealw/Charon
1
0
Fork 0
Code Issues Pull Requests Actions 14 Packages Projects Releases Wiki Activity
Files
0af08ee6274cb82995f8dbaee18ac8bb5e1663e6
Charon/GHCR_MIGRATION_SUMMARY.md
Wikid82 50d710ba7b chore: rename project artifacts to CPMP
2025-11-19 18:07:36 -05:00

7.0 KiB
Raw Blame History

GitHub Container Registry & Pages Setup Summary

✅ Changes Completed

Updated all workflows and documentation to use GitHub Container Registry (GHCR) instead of Docker Hub, and configured documentation to publish to GitHub Pages (not wiki).

🐳 Docker Registry Changes

What Changed:

  • Before: Docker Hub (docker.io/wikid82/caddy-proxy-manager-plus)
  • After: GitHub Container Registry (ghcr.io/wikid82/caddyproxymanagerplus)

Benefits of GHCR:

✅ No extra accounts needed - Uses your GitHub account ✅ Automatic authentication - Uses built-in GITHUB_TOKEN ✅ Free for public repos - No Docker Hub rate limits ✅ Integrated with repo - Packages show up on your GitHub profile ✅ Better security - No need to store Docker Hub credentials

Files Updated:

1. .github/workflows/docker-build.yml

  • Changed registry from docker.io to ghcr.io
  • Updated image name to use ${{ github.repository }} (automatically resolves to wikid82/caddyproxymanagerplus)
  • Changed login action to use GitHub Container Registry with GITHUB_TOKEN
  • Updated all image references throughout workflow
  • Updated summary outputs to show GHCR URLs

Key Changes:

# Before
env:
  REGISTRY: docker.io
  IMAGE_NAME: wikid82/caddy-proxy-manager-plus

# After
env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

# Before
- name: Log in to Docker Hub
  uses: docker/login-action@v3
  with:
    username: ${{ secrets.DOCKER_USERNAME }}
    password: ${{ secrets.DOCKER_PASSWORD }}

# After
- name: Log in to GitHub Container Registry
  uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

2. docs/github-setup.md

  • Removed entire Docker Hub setup section
  • Added GHCR explanation (no setup needed!)
  • Updated instructions for making packages public
  • Changed all docker pull commands to use ghcr.io
  • Updated troubleshooting for GHCR-specific issues
  • Added workflow permissions instructions

Key Sections Updated:

  • Step 1: Now explains GHCR is automatic (no secrets needed)
  • Troubleshooting: GHCR-specific error handling
  • Quick Reference: All commands use ghcr.io/wikid82/caddyproxymanagerplus
  • Checklist: Removed Docker Hub items, added workflow permissions

3. README.md

  • Updated Docker quick start command to use GHCR
  • Changed from wikid82/caddy-proxy-manager-plus to ghcr.io/wikid82/caddyproxymanagerplus

4. docs/getting-started.md

  • Updated Docker run command to use GHCR image path

📚 Documentation Publishing

GitHub Pages (Not Wiki)

Why Pages instead of Wiki:

  • ✅ Automated deployment - Deploys automatically via GitHub Actions
  • ✅ Beautiful styling - Custom HTML with dark theme
  • ✅ Version controlled - Changes tracked in git
  • ✅ Search engine friendly - Better SEO than wikis
  • ✅ Custom domain support - Can use your own domain
  • ✅ Modern features - Supports custom styling, JavaScript, etc.

Wiki limitations:

  • ❌ No automated deployment from Actions
  • ❌ Limited styling options
  • ❌ Separate from main repository
  • ❌ Less professional appearance

Workflow Configuration

The docs.yml workflow already configured for GitHub Pages:

  • Converts markdown to HTML
  • Creates beautiful landing page
  • Deploys to Pages on every docs change
  • No wiki integration needed or wanted

🚀 How to Use

For Users (Pulling Images):

Latest stable version:

docker pull ghcr.io/wikid82/cpmp:latest
docker run -d -p 8080:8080 -v caddy_data:/app/data ghcr.io/wikid82/cpmp:latest

Development version:

docker pull ghcr.io/wikid82/cpmp:dev

Specific version:

docker pull ghcr.io/wikid82/caddyproxymanagerplus:1.0.0

For Maintainers (Setup):

1. Enable Workflow Permissions

Required for pushing to GHCR:

  1. Go to Settings → Actions → General
  2. Scroll to Workflow permissions
  3. Select "Read and write permissions"
  4. Click Save

2. Enable GitHub Pages

Required for docs deployment:

  1. Go to Settings → Pages
  2. Under Build and deployment:
    • Source: "GitHub Actions"
  3. That's it!

3. Make Package Public (Optional)

After first build, to allow public pulls:

  1. Go to repository
  2. Click Packages (right sidebar)
  3. Click your package name
  4. Click Package settings
  5. Scroll to Danger Zone
  6. Change visibility → Public

🎯 What Happens Now

On Push to development:

  1. ✅ Builds Docker image
  2. ✅ Tags as dev
  3. ✅ Pushes to ghcr.io/wikid82/caddyproxymanagerplus:dev
  4. ✅ Tests the image
  5. ✅ Shows summary with pull command

On Push to main:

  1. ✅ Builds Docker image
  2. ✅ Tags as latest
  3. ✅ Pushes to ghcr.io/wikid82/caddyproxymanagerplus:latest
  4. ✅ Tests the image
  5. ✅ Converts docs to HTML
  6. ✅ Deploys to https://wikid82.github.io/CaddyProxyManagerPlus/

On Version Tag (e.g., v1.0.0):

  1. ✅ Builds Docker image
  2. ✅ Tags as 1.0.0, 1.0, 1, and sha-abc1234
  3. ✅ Pushes all tags to GHCR
  4. ✅ Tests the image

🔍 Verifying It Works

Check Docker Build:

  1. Push any change to development
  2. Go to Actions tab
  3. Watch "Build and Push Docker Images" run
  4. Check Packages section on GitHub
  5. Should see package with dev tag

Check Docs Deployment:

  1. Push any change to docs
  2. Go to Actions tab
  3. Watch "Deploy Documentation to GitHub Pages" run
  4. Visit https://wikid82.github.io/CaddyProxyManagerPlus/
  5. Should see your docs with dark theme!

📦 Image Locations

All images are now at:

ghcr.io/wikid82/caddyproxymanagerplus:latest
ghcr.io/wikid82/caddyproxymanagerplus:dev
ghcr.io/wikid82/caddyproxymanagerplus:1.0.0
ghcr.io/wikid82/caddyproxymanagerplus:1.0
ghcr.io/wikid82/caddyproxymanagerplus:1
ghcr.io/wikid82/caddyproxymanagerplus:sha-abc1234

View on GitHub:

https://github.com/Wikid82/CaddyProxyManagerPlus/pkgs/container/caddyproxymanagerplus

🎉 Benefits Summary

No More:

  • ❌ Docker Hub account needed
  • ❌ Manual secret management
  • ❌ Docker Hub rate limits
  • ❌ Separate image registry
  • ❌ Complex authentication

Now You Have:

  • ✅ Automatic authentication
  • ✅ Unlimited pulls (for public packages)
  • ✅ Images linked to repository
  • ✅ Free hosting
  • ✅ Better integration with GitHub
  • ✅ Beautiful documentation site
  • ✅ Automated everything!

📝 Files Modified

  1. .github/workflows/docker-build.yml - Complete GHCR migration
  2. docs/github-setup.md - Updated for GHCR and Pages
  3. README.md - Updated docker commands
  4. docs/getting-started.md - Updated docker commands

✅ Ready to Deploy!

Everything is configured and ready. Just:

  1. Set workflow permissions (Settings → Actions → General)
  2. Enable Pages (Settings → Pages → Source: GitHub Actions)
  3. Push to development to test
  4. Push to main to go live!

Your images will be at ghcr.io/wikid82/caddyproxymanagerplus and docs at https://wikid82.github.io/CaddyProxyManagerPlus/! 🚀

Reference in New Issue View Git Blame Copy Permalink