Custom Domains

Use your own domain names for your static sites

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.

Overview

The implementation uses a registration-based approach where domains are registered when users access their pages URL.

Architecture

Request Flow

Pages Domain Requests (Registration)

  • Requests to https://username.pages.example.com/repository are routed via high-priority pages router
  • The plugin parses user and repository identifiers from the URL
  • If a .pages file exists, the custom domain is registered in cache with a default TTL of 600 seconds

Custom Domain Requests (Lookup)

  • Requests to custom domains route through a low-priority catch-all router
  • The system performs a cache-only lookup for the domain mapping
  • If found, content is served; if not, a 404 is returned with guidance to activate via pages URL

Components

Configuration Fields:

  • enableCustomDomains: Toggle for custom domain functionality (default: enabled)
  • customDomainCacheTTL: Cache duration for domain mappings in seconds (default: 600)

Key Methods:

  • resolveCustomDomain(): Resolves domains using cache lookups only
  • registerCustomDomain(): Reads .pages files and registers mappings
  • parseCustomDomainPath(): Extracts file paths from custom domain requests

Caching Strategy

A dual-cache system manages both domain mappings and file content:

  1. Custom Domain Cache: Stores custom_domain:{domain} → username:repository mappings
  2. File Content Cache: Stores actual site files with separate TTL settings

Cache only contains active custom domains with no repository searching required, ensuring consistent sub-5ms response times for cached lookups.

Performance & Security

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.

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
  4. Visiting their pages URL to register the domain
  5. Accessing their custom domain

Visit pages URL periodically to refresh registration as cache entries expire.

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

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.

Limitations

  • Manual activation required via pages URL visit
  • Cache expiration requires periodic refreshing
  • Single custom domain per repository supported
  • Uses only Go standard library for Yaegi interpreter compatibility

Testing

Testing covers path parsing, cache resolution, routing scenarios, and configuration defaults with 65.4% overall coverage.