Custom Domain Redirects

Custom domain redirects enable automatic visitor redirection from one URL to another. This feature is useful for page renaming, creating short URLs, site reorganization, and maintaining SEO rankings.

Prerequisites

• Repository with a .pages file
• Custom domain configured in .pages file
• DNS configured and pointing to Bovine Pages Server
• Custom domain registered by visiting your pages URL

How It Works

1. Create a .redirects file in your repository root
2. Visit https://your-custom-domain.com/LOAD_REDIRECTS to activate
3. Server reads redirects and configures Traefik to handle them
4. Traefik automatically redirects visitors using 301 permanent redirects
5. Redirects are stored persistently in Redis cache

Setup Steps

Step 1: Create .redirects File

Create a .redirects file in your repository root with the format FROM:TO (one redirect per line):

• FROM = URL path to redirect from
• TO = URL path or absolute URL to redirect to
• Lines starting with # are treated as comments
• Empty lines are allowed

Example .redirects file:

# Simple page rename
about.html:about-us.html

# Directory reorganization
posts/first-post:blog/first-post
posts/second-post:blog/second-post

# Short URLs
docs:documentation/getting-started/index.html

# External redirect
github:https://github.com/yourusername

Step 2: Verify .pages File

Ensure your .pages file has a custom domain configured:

enabled: true
custom_domain: www.example.com

Step 3: Commit and Push

Commit your .redirects file and push to your repository:

git add .redirects
git commit -m "Add URL redirects"
git push

Step 4: Activate Redirects

Visit the special endpoint to load your redirects:

https://www.example.com/LOAD_REDIRECTS

You’ll see a success page displaying all your active redirects.

Step 5: Test Redirects

Test your redirects by visiting the original URLs to verify they redirect correctly.

Redirect Examples

Simple Page Rename

about.html:about-us.html

Directory Reorganization

posts/first-post:blog/first-post
posts/second-post:blog/second-post

Short URLs

docs:documentation/getting-started/index.html

External Redirects

github:https://github.com/yourusername
linkedin:https://linkedin.com/in/yourprofile

Trailing Slashes

about:about/
blog/:blog

Root to Subdirectory

/:app/

Updating Redirects

To update your redirects:

1. Edit the .redirects file in your repository
2. Commit and push the changes
3. Reload via https://your-custom-domain.com/LOAD_REDIRECTS

Resource Limits

The default maximum is 25 redirects per domain. The server reads only the first 25 lines of your .redirects file.

Troubleshooting

Security Considerations

Allowed Use Cases

• Redirecting between pages on your site
• Redirecting to external websites
• Creating short URLs
• Site reorganization

Not Allowed

• JavaScript injection attempts
• HTML injection attempts
• Code execution attempts
• Accessing other users’ repositories

Best Practices

• Use 301 redirects (automatic)
• Avoid redirect chains (A→B→C)
• Test thoroughly before relying on redirects
• Document redirect purposes with comments
• Clean up old redirects after sufficient time

Limitations

1. Custom domains only - Redirects do not work on standard pages domain URLs
2. Redis required - Redis cache must be enabled on the server
3. Manual activation - Must visit /LOAD_REDIRECTS endpoint after changes
4. Maximum redirects - Default limit of 25 redirects per domain
5. 301 redirects only - All redirects are permanent (301)
6. No wildcard support - Each redirect must be explicitly defined

Advanced Topics

Multiple Domains

Each repository can have independent redirects. If you use multiple custom domains pointing to the same repository, each domain can have its own redirect configuration.

Redirect Priority

When multiple redirects could match, the first matching redirect wins. Order your redirects carefully in the .redirects file.

Performance

Redirects have zero performance impact on your site. Traefik handles redirects at the network level with sub-millisecond overhead (<1ms).

Complete Example

Here’s a complete example showing blog reorganization:

Repository structure:

.
├── .pages
├── .redirects
└── public/
    ├── index.html
    ├── blog/
    │   ├── 2024-01-post.html
    │   └── 2024-02-post.html
    └── old-posts/
        ├── first.html
        └── second.html

.pages file:

enabled: true
custom_domain: blog.example.com

.redirects file:

# Reorganize old posts
old-posts/first.html:blog/2024-01-post.html
old-posts/second.html:blog/2024-02-post.html

# Short URLs
latest:blog/2024-02-post.html

Activation:

1. Push the repository
2. Visit https://blog.example.com/LOAD_REDIRECTS
3. Test: https://blog.example.com/old-posts/first.html → redirects to https://blog.example.com/blog/2024-01-post.html

Technical Details

The redirect feature uses Traefik’s redirectregex middleware with the following characteristics:

• Configuration stored in Redis with persistent TTL
• Middleware dynamically generated from .redirects file
• All redirects use HTTP 301 (Permanent Redirect)
• Special characters automatically escaped for regex safety
• Implementation in redirects.go