forgejopages

Caddy Forgejo Pages

⚠️ DEVELOPMENT WARNING ⚠️
This project is currently in active development and is NOT ready for production use.
Features may be incomplete, unstable, or subject to breaking changes.
Use at your own risk and avoid deploying in production environments.

A Caddy module that enables automatic deployment of static sites from Forgejo/Gitea repositories via webhooks, similar to GitHub Pages or GitLab Pages.

⚠️ Current Status

This is an early-stage development project with the following limitations:

• 🚧 Alpha software - Core functionality still being implemented
• 🐛 Known bugs - Several features may not work as expected
• 🔄 Breaking changes - API and configuration may change without notice
• 📚 Limited documentation - Setup guides may be incomplete
• 🧪 Testing required - Minimal real-world testing completed
• 🔒 Security review needed - Not audited for production security

DO NOT USE IN PRODUCTION until we reach a stable v1.0.0 release.

Features

• 🔄 Automatic Deployment: Deploy sites automatically via webhooks
• 🌐 Custom Domains: Support for custom domains via .domain files
• 🚀 Dynamic Configuration: Updates Caddy configuration without restarts
• 📦 Lazy Loading: Repositories cloned on first access
• 🔒 Secure: HMAC webhook signature validation
• 📧 Notifications: Email notifications for deployment errors
• 🧹 Auto Cleanup: Automatic cleanup of unused sites

URL Patterns

• https://username.pages.example.com → Default repository, main branch
• https://username.pages.example.com/repository → Specific repository, main branch
• https://username.pages.example.com/repository/@branch → Specific repository and branch
• https://custom.com → Custom domain (if .domain file present)

Installation

Using xcaddy

xcaddy build --with codeberg.org/YOURUSERNAME/caddy-forgejo-pages

Manual Build

go install github.com/caddyserver/xcaddy/cmd/xcaddy@latest
xcaddy build --with codeberg.org/YOURUSERNAME/caddy-forgejo-pages

Configuration

Caddyfile

{
    forgejo_pages {
        base_domain "pages.example.com"
        storage_path "/var/caddy-pages"
        cleanup_days 30
        notification_email "admin@example.com"
        smtp_server "smtp.example.com:587"
        smtp_username "notifications@example.com"
        smtp_password "your-smtp-password"
        webhook_secret "your-webhook-secret"
    }
}

*.pages.example.com {
    forgejo_pages
    respond "Site not found" 404
}

example.com {
    forgejo_pages
    file_server
}

JSON Configuration

{
    "apps": {
        "forgejo_pages": {
            "base_domain": "pages.example.com",
            "storage_path": "/var/caddy-pages",
            "cleanup_days": 30,
            "notification_email": "admin@example.com",
            "smtp_server": "smtp.example.com:587",
            "smtp_username": "notifications@example.com",
            "smtp_password": "your-smtp-password",
            "webhook_secret": "your-webhook-secret"
        }
    }
}

Usage

1. Setup Repository: Create a repository with static files
2. Custom Domain (optional): Add a .domain file with your custom domain
3. Configure Webhook: Add webhook URL: https://example.com/.well-known/forgejo-pages/webhook
4. Push Changes: Push to trigger automatic deployment

Configuration Options

Repository Structure

Your repository should contain:

• index.html - Main page
• .domain - (Optional) Custom domain on first line
• Static assets (CSS, JS, images, etc.)

License

MIT License - see LICENSE file for details.

Contributing

Pull requests welcome! Please see CONTRIBUTING.md for guidelines.