Charon/docs/github-setup.md

🔧 GitHub Setup Guide

This guide will help you set up GitHub Actions for automatic Docker builds and documentation deployment.

---

📦 Step 1: Docker Image Publishing (Automatic!)

The Docker build workflow uses GitHub Container Registry (GHCR) to store your images. No setup required! GitHub automatically provides authentication tokens for GHCR.

How It Works

GitHub Actions automatically uses the built-in secret token to authenticate with GHCR. We recommend creating a GITHUB_TOKEN secret (preferred); workflows currently still work with CPMP_TOKEN for backward compatibility.

• ✅ Push images to ghcr.io/wikid82/charon
• ✅ Link images to your repository
• ✅ Publish images for free (public repositories)

Nothing to configure! Just push code and images will be built automatically.

Make Your Images Public (Optional)

By default, container images are private. To make them public:

1. Go to your repository → https://github.com/Wikid82/charon
2. Look for "Packages" on the right sidebar (after first build)
3. Click your package name
4. Click "Package settings" (right side)
5. Scroll down to "Danger Zone"
6. Click "Change visibility" → Select "Public"

Why make it public? Anyone can pull your Docker images without authentication!

---

📚 Step 2: Enable GitHub Pages (For Documentation)

Your documentation will be published to GitHub Pages (not the wiki). Pages is better for auto-deployment and looks more professional!

Enable Pages

1. Go to your repository → https://github.com/Wikid82/charon
2. Click "Settings" (top menu)
3. Click "Pages" (left sidebar under "Code and automation")
4. Under "Build and deployment":
   • Source: Select "GitHub Actions" (not "Deploy from a branch")
5. That's it! No other settings needed.

Once enabled, your docs will be live at:

https://wikid82.github.io/charon/

Note: The first deployment takes 2-3 minutes. Check the Actions tab to see progress!

---

🚀 How the Workflows Work

Docker Build Workflow (.github/workflows/docker-build.yml)

Triggers when:

• ✅ You push to main branch → Creates latest tag
• ✅ You push to development branch → Creates dev tag
• ✅ You create a version tag like v1.0.0 → Creates version tags
• ✅ You manually trigger it from GitHub UI

What it does:

1. Builds the frontend
2. Builds a Docker image for multiple platforms (AMD64, ARM64)
3. Pushes to Docker Hub with appropriate tags
4. Tests the image by starting it and checking the health endpoint
5. Shows you a summary of what was built

Tags created:

• latest - Always the newest stable version (from main)
• dev - The development version (from development)
• 1.0.0, 1.0, 1 - Version numbers (from git tags)
• sha-abc1234 - Specific commit versions

Where images are stored:

• ghcr.io/wikid82/charon:latest
• ghcr.io/wikid82/charon:dev
• ghcr.io/wikid82/charon:1.0.0

Documentation Workflow (.github/workflows/docs.yml)

Triggers when:

• ✅ You push changes to docs/ folder
• ✅ You update README.md
• ✅ You manually trigger it from GitHub UI

What it does:

1. Converts all markdown files to beautiful HTML pages
2. Creates a nice homepage with navigation
3. Adds dark theme styling (matches the app!)
4. Publishes to GitHub Pages
5. Shows you the published URL

---

🎯 Testing Your Setup

Test Docker Build

1. Make a small change to any file

2. Commit and push to development:

   git add .
   git commit -m "test: trigger docker build"
   git push origin development
   

3. Go to Actions tab on GitHub

4. Watch the "Build and Push Docker Images" workflow run

5. Check Packages on your GitHub profile for the new dev tag!

Test Docs Deployment

1. Make a small change to README.md or any doc file

2. Commit and push to main:

   git add .
   git commit -m "docs: update readme"
   git push origin main
   

3. Go to Actions tab on GitHub

4. Watch the "Deploy Documentation to GitHub Pages" workflow run

5. Visit your docs site (shown in the workflow summary)!

---

🏷️ Creating Version Releases

When you're ready to release a new version:

1. Tag your release:

   git tag -a v1.0.0 -m "Release version 1.0.0"
   git push origin v1.0.0
   

2. The workflow automatically:

   • Builds Docker image
   • Tags it as 1.0.0, 1.0, and 1
   • Pushes to Docker Hub
   • Tests it works

3. Users can pull it:

   docker pull ghcr.io/wikid82/charon:1.0.0
   docker pull ghcr.io/wikid82/charon:latest
   

---

🐛 Troubleshooting

Docker Build Fails

Problem: "Error: denied: requested access to the resource is denied"

• Fix: This shouldn't happen with GITHUB_TOKEN or CPMP_TOKEN - check workflow permissions
• Verify: Settings → Actions → General → Workflow permissions → "Read and write permissions" enabled

Problem: Can't pull the image

• Fix: Make the package public (see Step 1 above)
• Or: Authenticate with GitHub: echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin (or CPMP_TOKEN for backward compatibility)

Docs Don't Deploy

Problem: "deployment not found"

• Fix: Make sure you selected "GitHub Actions" as the source in Pages settings
• Not: "Deploy from a branch"

Problem: Docs show 404 error

• Fix: Wait 2-3 minutes after deployment completes
• Fix: Check the workflow summary for the actual URL

General Issues

Check workflow logs:

1. Go to Actions tab
2. Click the failed workflow
3. Click the failed job
4. Expand the step that failed
5. Read the error message

Still stuck?

• Open an issue: https://github.com/Wikid82/charon/issues
• We're here to help!

---

📋 Quick Reference

Docker Commands

# Pull latest development version
docker pull ghcr.io/wikid82/charon:dev

# Pull stable version
docker pull ghcr.io/wikid82/charon:latest

# Pull specific version
docker pull ghcr.io/wikid82/charon:1.0.0

# Run the container
docker run -d -p 8080:8080 -v caddy_data:/app/data ghcr.io/wikid82/charon:latest

Git Tag Commands

# Create a new version tag
git tag -a v1.2.3 -m "Release 1.2.3"

# Push the tag
git push origin v1.2.3

# List all tags
git tag -l

# Delete a tag (if you made a mistake)
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3

Trigger Manual Workflow

1. Go to Actions tab
2. Click the workflow name (left sidebar)
3. Click "Run workflow" button (right side)
4. Select branch
5. Click "Run workflow"

---

✅ Checklist

Before pushing to production, make sure:

• GitHub Pages is enabled with "GitHub Actions" source
• You've tested the Docker build workflow (automatic on push)
• You've tested the docs deployment workflow
• Container package is set to "Public" visibility (optional, for easier pulls)
• Documentation looks good on the published site
• Docker image runs correctly
• You've created your first version tag

---

🎉 You're Done

Your CI/CD pipeline is now fully automated! Every time you:

• Push to main → New latest Docker image + updated docs
• Push to development → New dev Docker image for testing
• Create a tag → New versioned Docker image

No manual building needed! 🚀

Questions? Check the GitHub Actions docs or open an issue!