Domain Management

Use your own domain names for your static sites or use a .profile or standard URL

Let’s first of all look at how domains work with Bovine Pages Server. There are three main types of domain/URL patters:

URL Patterns

Bovine Pages supports three types of URLs:

1. Repository Sites

https://john.pages.example.com/blog/
  • Serves from john/blog/public/
  • One site per repository
  • Perfect for project documentation or blogs

2. Profile Sites

https://john.pages.example.com/
  • Serves from john/.profile/public/
  • Create a repository called .profile
  • Your personal homepage

3. Custom Domains

https://www.yourblog.com/
  • Serves from any repository with custom_domain set
  • Automatic HTTPS with Let’s Encrypt

Repository and .profile sites will work out the box and depending on the pages domain your admin set up will depend on the final URL you need. Custom domain support allows you to serve your static sites on your own domain names (e.g., www.example.com) instead of or in addition to the default pages domain format. However theres some setup you need to do.

Using custom Domains

The implementation uses a registration-based approach where domains are registered when users access their pages URL. All requests remain fast through cache-only lookups with no repository searching. Security is maintained by respecting repository visibility settings and limiting access based on authentication tokens when needed.

Traefik Configuration

Two routers with different priorities handle routing:

  • High-priority router (10) handles *.pages.example.com
  • Low-priority router (1) catches remaining domains

Traefik automatically provisions SSL certificates for custom domains via configured certificate resolvers. So you get automatic domain registration for your custome domain.

User Setup

Users activate custom domains by:

  1. Creating a repository with static files in a public/ folder
  2. Adding custom_domain: www.example.com to their .pages file
  3. Configuring DNS records pointing to the Traefik server (you may need to verify your DNS with a txt record)
  4. Visiting their pages URL to register the domain
  5. Accessing their custom domain

DNS Verification (Optional)

DNS verification is an optional security enhancement that administrators can enable to verify domain ownership before allowing custom domain registration.

How It Works

When DNS verification is enabled, the system performs a DNS TXT record lookup on the custom domain to confirm ownership. The TXT record must contain a specific verification hash that proves the user owns both the domain and the repository.

Enabling DNS Verification

Administrators can enable this feature by setting enableCustomDomainDNSVerification: true in the middleware configuration. When disabled (default), users can skip the verification step.

User Setup with DNS Verification

When DNS verification is enabled, users must complete these additional steps:

1. Generate Verification Hash

Calculate the SHA256 hash of your repository path in the format owner/repository:

# Example for repository squarecows/bovine-website
echo -n "squarecows/bovine-website" | sha256sum
# Result: 73bb8214899661e7f7900c77714586cc51702e6cf26a58c62e17fa9d88f3d3d3

Alternatively you can use the easy Generator tool hosted here.

2. Create DNS TXT Record

Add a TXT record to your domain with the following format:

TXT www.example.com bovine-pages-verification=73bb8214899661e7f7900c77714586cc51702e6cf26a58c62e17fa9d88f3d3d3

The record pattern is: bovine-pages-verification=<SHA256_HASH>

3. Configure DNS A/CNAME Record

Add your A or CNAME record pointing to the Traefik server:

A    www.example.com  192.0.2.1
# or
CNAME www.example.com  traefik.example.com

4. Verify DNS Propagation

Before activating, verify your DNS records have propagated:

# Check TXT record
dig TXT www.example.com

# Check A/CNAME record
dig www.example.com

5. Activate Custom Domain

Visit your pages URL to register the domain. The plugin will verify the TXT record on each access.