Custom Domain Redirects

This guide shows you how to set up URL redirects for your custom domain sites hosted on Bovine Pages Server.

Overview

Redirects allow you to automatically send visitors from one URL to another. This is useful for:

• Renaming pages: Redirect old URLs to new locations
• Short URLs: Create memorable shortcuts to longer paths
• Site reorganization: Update your site structure without breaking old links
• SEO: Maintain search engine rankings when moving content

Important: Redirects only work on custom domains, not standard pages domain URLs (e.g., username.pages.example.com/repository).

Prerequisites

Before setting up redirects, you must have:

1. ✅ A repository with a .pages file
2. ✅ A custom domain configured in your .pages file
3. ✅ DNS configured and pointing to the Bovine Pages Server
4. ✅ Custom domain registered (by visiting your pages URL)

If you haven't set up a custom domain yet, see the Custom Domains wiki page first.

How It Works

When you set up redirects:

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

This means:

• ⚡ Fast: Traefik handles redirects directly (no plugin overhead)
• 🔄 Persistent: Redirects remain active until you reload them
• 📊 SEO-friendly: 301 redirects preserve search engine rankings

Step-by-Step Setup

Step 1: Create .redirects File

In your repository root (same level as .pages file), create a file named .redirects:

# Redirect format: FROM:TO
# Lines starting with # are comments
# Empty lines are ignored

# Rename a page
old-page:new-page

# Redirect to a subdirectory
index.html:home/

# Reorganize blog posts
blog/old-post:blog/new-post

# Short URL to long path
docs:documentation/getting-started/

# Absolute URLs (external redirects)
external:https://example.com/page

File Format Rules:

• One redirect per line
• Format: FROM:TO
• FROM = URL path to redirect from
• TO = URL path or absolute URL to redirect to
• Comments start with #
• Empty lines are allowed
• Whitespace around colons is ignored

Step 2: Verify Your .pages File

Make sure your .pages file has a custom domain configured:

enabled: true
custom_domain: www.example.com

Remember: Redirects only work on custom domains!

Step 3: Commit and Push

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

Step 4: Activate Redirects

Visit the special activation URL using your custom domain:

https://www.example.com/LOAD_REDIRECTS

Replace www.example.com with your actual custom domain.

You should see a success page with:

• ✅ Confirmation that redirects were loaded
• 📝 List of all active redirects
• 🔄 Instructions for updating redirects

Step 5: Test Your Redirects

Try visiting one of your redirect URLs:

https://www.example.com/old-page

You should be automatically redirected to the new location:

https://www.example.com/new-page

Redirect Examples

Simple Page Rename

Scenario: You renamed about.html to about-us.html

about.html:about-us.html

Visitors to https://www.example.com/about.html are redirected to https://www.example.com/about-us.html

Directory Reorganization

Scenario: You moved all blog posts from /posts/ to /blog/

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

Short URLs

Scenario: You want a short URL for your documentation

docs:documentation/getting-started/index.html
contact:about/contact-form.html

Now visitors can use:

• https://www.example.com/docs → Full documentation
• https://www.example.com/contact → Contact form

External Redirects

Scenario: You want to redirect to an external site

github:https://github.com/yourusername
twitter:https://twitter.com/yourusername
donate:https://donate.example.org/campaign

Trailing Slashes

Scenario: You want consistent URL formats

# Redirect to add trailing slash
about:about/
products:products/

# Redirect to remove trailing slash
blog/:blog
docs/:docs

Root to Subdirectory

Scenario: Your main content is in a subdirectory

index.html:app/index.html
/:app/

Updating Redirects

To add, remove, or modify redirects:

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

Important: You must reload redirects after every change. They don't update automatically.

Resource Limits

To prevent resource exhaustion, the server admin can configure a maxRedirects limit (default: 25).

This means:

• Maximum 25 redirect rules per domain (default)
• The plugin reads only the first 25 lines of your .redirects file
• Contact your admin if you need more redirects

Tip: Use general patterns rather than individual rules when possible.

Troubleshooting

Error: "Custom domain not configured"

Problem: Your .pages file doesn't have a custom_domain field.

Solution:

1. Edit your .pages file to add custom_domain: www.example.com
2. Commit and push
3. Register your custom domain by visiting https://username.pages.example.com/repository
4. Try loading redirects again

Error: "No .redirects file found"

Problem: The .redirects file doesn't exist or is in the wrong location.

Solution:

1. Create .redirects in your repository root (same directory as .pages)
2. Make sure it's named exactly .redirects (with the leading dot)
3. Commit and push
4. Try loading redirects again

Error: "Redis cache required for redirects"

Problem: Your Bovine Pages Server isn't configured with Redis.

Solution: Redirects require Redis cache. Contact your server administrator to enable Redis support.

Redirects Not Working

Possible causes:

1. Haven't loaded redirects: Visit https://your-custom-domain.com/LOAD_REDIRECTS
2. Custom domain not registered: Visit https://username.pages.example.com/repository first
3. DNS not configured: Verify your DNS A/CNAME record points to the server
4. Invalid format: Check your .redirects file format (must be FROM:TO)
5. Too many redirects: Exceeded maxRedirects limit (default: 25)

Redirect Shows Instead of Working

Problem: Visiting /LOAD_REDIRECTS shows a file instead of loading redirects.

Cause: You're using the pages domain URL, not the custom domain URL.

Solution:

• ❌ Wrong: https://username.pages.example.com/repository/LOAD_REDIRECTS
• ✅ Correct: https://www.example.com/LOAD_REDIRECTS

Changes Not Appearing

Problem: Updated .redirects file but changes aren't active.

Solution: You must reload redirects after every change:

1. Commit and push your changes
2. Visit https://your-custom-domain.com/LOAD_REDIRECTS again

Security Considerations

What Redirects Can Do

✅ Allowed:

• Redirect to different pages on your site
• Redirect to external websites (absolute URLs)
• Create short URLs
• Reorganize site structure

❌ Not Allowed:

• JavaScript injection
• HTML injection
• Code execution
• Accessing other users' repositories

Best Practices

1. Use 301 redirects: Bovine uses 301 (permanent) redirects automatically
2. Avoid redirect chains: Don't redirect A→B→C, instead redirect A→C directly
3. Test thoroughly: Verify all redirects work before relying on them
4. Document changes: Add comments in .redirects explaining why redirects exist
5. Clean up old redirects: Remove redirects after sufficient time has passed

Limitations

1. Custom domains only: Redirects don't work on username.pages.example.com/repository URLs
2. Redis required: Your server must have Redis cache enabled
3. Manual activation: Must visit /LOAD_REDIRECTS to load/update redirects
4. Maximum redirects: Limited by maxRedirects configuration (default: 25)
5. 301 permanent: All redirects are permanent (301), not temporary (302)
6. No wildcards: Each redirect must be explicit (no pattern matching)

Advanced Topics

Checking Active Redirects

When you visit /LOAD_REDIRECTS, the success page shows all active redirects:

✅ Successfully loaded 3 redirects for www.example.com

Active redirects:
  • old-page → new-page
  • index.html → home/
  • blog/old-post → blog/new-post

Multiple Custom Domains

If you have multiple repositories with custom domains:

• Each repository has its own .redirects file
• Each custom domain has independent redirects
• Load redirects separately for each domain

Redirect Priority

If you have overlapping redirects:

• First matching redirect wins
• Order matters in your .redirects file
• More specific redirects should come before general ones

Performance Impact

Redirects have zero performance impact on your site:

• Traefik handles redirects at the network level
• No plugin code execution for redirects
• Response time: <1ms for redirects
• Your pages still serve at normal speed

Complete Example

Here's a complete example setup for a blog that was reorganized:

Repository structure:

my-blog/
├── .pages
├── .redirects
└── public/
    ├── index.html
    ├── blog/
    │   ├── post-1.html
    │   └── post-2.html
    └── about.html

.pages file:

enabled: true
custom_domain: blog.example.com

.redirects file:

# Blog reorganization - migrated from old structure

# Old homepage
home.html:index.html

# Old blog posts moved from /posts/ to /blog/
posts/my-first-post:blog/post-1.html
posts/getting-started:blog/post-2.html

# Renamed about page
about-me.html:about.html

# Short URLs
contact:about.html#contact
rss:feed.xml

# External social links
twitter:https://twitter.com/myblog
github:https://github.com/myblog

Activation steps:

1. Commit files: git add .pages .redirects public/ && git commit -m "Set up blog with redirects" && git push
2. Register custom domain: Visit https://username.pages.example.com/my-blog
3. Load redirects: Visit https://blog.example.com/LOAD_REDIRECTS
4. Test: Visit https://blog.example.com/posts/my-first-post (should redirect to /blog/post-1.html)

Getting Help

If you encounter issues:

1. Check server logs: Ask your administrator to check Traefik logs
2. Verify configuration: Ensure .pages has custom_domain and custom domain is registered
3. Test DNS: Use dig or nslookup to verify DNS is configured correctly
4. Read error messages: The /LOAD_REDIRECTS page provides detailed error messages
5. Contact support: Reach out to your Bovine Pages Server administrator

Related Documentation

• Custom Domains - Set up custom domains first
• Quick Start - Basic Bovine Pages setup
• Cache Management - Understanding caching behavior

Technical Details

For administrators and developers interested in the technical implementation:

• Redirects use Traefik's redirectregex middleware
• Configuration is stored in Redis with persistent TTL
• Middleware is dynamically generated from .redirects file
• All redirects are 301 (permanent)
• Special characters are automatically escaped for regex safety
• Implementation: redirects.go in the plugin codebase

---

Note: This feature requires Bovine Pages Server v0.1.1 or later.