Quick Start - User Guide

Bovine Pages Server - User Guide

Everything you want publicly accessible goes in public/. The plugin only serves files from this folder. However the .pages file lives in the root of your repo.

my-website/
├── .pages              # Config (not served)
├── README.md           # Not served
├── scripts/            # Not served
└── public/             # ← Only this is served
    ├── index.html      # https://you.pages.example.com/repo/
    ├── about.html      # https://you.pages.example.com/repo/about.html
    ├── pricing/
    │   └── index.html  # https://you.pages.example.com/repo/pricing/
    └── assets/
        ├── style.css   # https://you.pages.example.com/repo/assets/style.css
        └── logo.png    # https://you.pages.example.com/repo/assets/logo.png

This guide shows you how to host your static sites using Bovine Pages. If you’re familiar with GitHub Pages, this’ll feel natural.

Your First Site in 3 Steps

1. Create Your Repository

In your Forgejo instance, create a new repository (e.g., my-website) and add your site files:

my-website/
├── .pages           # Required config file
└── public/          # Your actual site
    ├── index.html
    ├── style.css
    └── script.js

2. Add the .pages File

Create a .pages file in your repository root:

enabled: true

That’s it - the minimal config. Push this up:

git add .pages public/
git commit -m "Enable Bovine Pages"
git push

3. Visit Your Site

Your site is now live at:

https://your-username.pages.example.com/my-website/

The URL format is always: https://{username}.{pages-domain}/{repository}/

Using Custom Domains

Want your site at your own domain? Here’s the complete flow from DNS to SSL:

1: Configure DNS

Point your domain to the Traefik server:

# At your DNS provider, create:
www.yoursite.com  A  123.456.789.012  # Your Traefik IP

# Or use a CNAME:
www.yoursite.com  CNAME  traefik.example.com

2: Update Your .pages File

enabled: true
custom_domain: www.yoursite.com

3: Activate the Domain

Visit your pages URL first to register the custom domain:

https://your-username.pages.example.com/my-website/

This tells Bovine Pages about your custom domain. Behind the scenes, it:

1. Registers the mapping: www.yoursite.com → your-username/my-website
2. Creates a Traefik router for your domain
3. Requests an SSL certificate from Let’s Encrypt

4: Visit Your Custom Domain

After 1-2 minutes (for DNS propagation and SSL generation):

https://www.yoursite.com/

Your site loads with a valid SSL certificate, automatically.

DNS Verification (If Required)

Some Bovine Pages instances require proof that you own the domain. If your admin has enabled this:

Generate your verification hash:

# Format: owner/repository
echo -n "your-username/my-website" | shasum -a 256
# Output: abc123def456...

or use the DNS Hash Generator on this site.

Add a DNS TXT record:

TXT  www.yoursite.com  bovine-pages-verification=abc123def456...

Then proceed set up as normal

Bovine will now check that the hash matches the domain and the repository when registering the custom domain and refuses to do so if they don’t match.

DNS verification prevents domain hijacking - someone can’t claim google.com just by putting it in their .pages file.

Advanced .pages Configuration

Here’s everything you can put in a .pages file:

# Required
enabled: true

# Optional features
custom_domain: www.example.com           # Custom domain
password: abc123...                      # SHA256 password hash
directory_listings: true                 # Show directory indexes

That’s it - the plugin is designed to be minimal by default.