Redirect Rules

Configure HTTP redirects and URL rewrites for your applications

Overview

Dokploy supports flexible HTTP redirect rules through Traefik middleware. Redirects allow you to route traffic based on regex patterns, enabling URL canonicalization, legacy path support, and complex routing scenarios.

Understanding Redirects

Redirects in Dokploy use regex pattern matching to transform incoming URLs:

• Regex: Pattern to match against the incoming request path
• Replacement: Target URL or path to redirect to
• Permanent: HTTP status code (301 vs 302)

Redirects are processed before the request reaches your application, making them efficient for handling URL transformations at the proxy level.

Creating Redirect Rules

1. Navigate to application

   Open your application in the Dokploy dashboard.

2. Access redirects

   Click on the Redirects tab.

3. Add redirect rule

   Click Add Redirect and configure:

   • Regex: Regular expression to match URLs
   • Replacement: Target URL or path
   • Permanent: Toggle for 301 (permanent) vs 302 (temporary)
4. Test and deploy

   Save the redirect. Changes are applied immediately to Traefik.

Redirect Types

Permanent Redirects (301)

Use permanent redirects when URLs have moved permanently. Search engines will update their indexes.

{
  regex: "^/old-path",
  replacement: "/new-path",
  permanent: true
}

Browsers and search engines cache 301 redirects aggressively. Use 302 for testing.

Temporary Redirects (302)

Use temporary redirects for maintenance pages, A/B testing, or when URLs might change back.

{
  regex: "^/maintenance",
  replacement: "/under-construction",
  permanent: false
}

Common Redirect Patterns

Domain Redirect

Redirect from one domain to another:

{
  regex: "^https?://old-domain\\.com/(.*)",
  replacement: "https://new-domain.com/$1",
  permanent: true
}

This preserves the path and query string while changing the domain.

HTTPS Enforcement

Force HTTPS for all requests:

{
  regex: "^http://example\\.com/(.*)",
  replacement: "https://example.com/$1",
  permanent: true
}

This is typically handled by Traefik automatically when HTTPS is enabled on domains.

Path Normalization

Remove trailing slashes:

{
  regex: "^/(.*)/+$",
  replacement: "/$1",
  permanent: true
}

Or ensure trailing slashes:

{
  regex: "^/(.+[^/])$",
  replacement: "/$1/",
  permanent: true
}

Subdirectory to Subdomain

Convert paths to subdomains:

{
  regex: "^/blog/(.*)",
  replacement: "https://blog.example.com/$1",
  permanent: true
}

Advanced Regex Patterns

Capture Groups

Use parentheses () to capture parts of the URL for reuse:

// Redirect blog posts with year/month/slug to new structure
{
  regex: "^/blog/(\\d{4})/(\\d{2})/(.+)$",
  replacement: "/articles/$3",
  permanent: true
}

// Example: /blog/2024/02/my-post → /articles/my-post

Multiple Captures

// Preserve year but flatten structure
{
  regex: "^/archive/(\\d{4})/(.+)$",
  replacement: "/$1-$2",
  permanent: true
}

// Example: /archive/2024/article → /2024-article

Optional Segments

// Match with or without www
{
  regex: "^https?://(www\\.)?example\\.com/(.*)",
  replacement: "https://example.com/$2",
  permanent: true
}

Query String Handling

Preserve query strings in redirects:

{
  regex: "^/old-page\\?*(.*)",
  replacement: "/new-page?$1",
  permanent: true
}

// Example: /old-page?id=123 → /new-page?id=123

Be cautious with query strings. Traefik automatically preserves them in most cases.

Multiple Redirects

Redirects are processed in order. The first matching rule wins.

Rule Priority

// Rule 1: Specific path
{
  regex: "^/special/page$",
  replacement: "/custom-destination",
  permanent: true
}

// Rule 2: Catch-all for /special/*
{
  regex: "^/special/(.*)",
  replacement: "/general/$1",
  permanent: true
}

Order matters: /special/page matches Rule 1 and stops. Other /special/* paths match Rule 2.

Chaining Redirects

Avoid redirect chains. Each redirect adds latency and can confuse search engines.

Bad: A → B → C (two hops)

Good: A → C and B → C (direct redirects)

Use Cases

Legacy URL Support

Maintain old URLs when restructuring:

{
  regex: "^/products/(.*)",
  replacement: "/shop/$1",
  permanent: true
}

Locale Redirects

Route users to localized content:

{
  regex: "^/en/(.*)",
  replacement: "https://en.example.com/$1",
  permanent: false
}

API Versioning

Redirect deprecated API versions:

{
  regex: "^/api/v1/(.*)",
  replacement: "/api/v2/$1",
  permanent: false
}

Marketing Campaigns

Vanity URLs for campaigns:

{
  regex: "^/promo",
  replacement: "/landing/special-offer",
  permanent: false
}

SEO Considerations

301 vs 302 Impact

301 Permanent

Use when:

• Content moved permanently
• Domain migrations
• Site restructuring

SEO Effect:

• Passes 90-99% of link equity
• Search engines update index
• Cached by browsers

302 Temporary

Use when:

• A/B testing
• Maintenance pages
• Temporary campaigns

SEO Effect:

• Original URL stays in index
• Link equity not transferred
• Not cached long-term

Best Practices

1. Minimize redirect chains

   Each redirect adds ~100-300ms latency. Keep chains to maximum 1 hop.

2. Use 301 for permanent changes

   Search engines need clear signals about URL changes.

3. Preserve URL structure when possible

   Keep paths similar to maintain user expectations.

4. Monitor 404s

   Create redirects for commonly accessed missing pages.

Testing Redirects

Command Line Testing

# Test redirect response
curl -I https://example.com/old-path

# Follow redirects and show final URL
curl -L -I https://example.com/old-path

# Show all redirect hops
curl -L -v https://example.com/old-path 2>&1 | grep "< location:"

Expected Output

HTTP/2 301
location: https://example.com/new-path

Test redirects in incognito/private mode to avoid browser caching issues.

Troubleshooting

Redirect Not Working

Check:

1. Regex pattern is valid and matches test URLs
2. Redirect is saved and deployed
3. Traefik configuration reloaded
4. No conflicting redirect rules

Debug:

# Check Traefik logs
docker logs dokploy-traefik --tail 100

# Test regex pattern
echo "/old-path" | grep -E "^/old-path"

Redirect Loop

Symptoms: Browser shows “Too many redirects” error

Cause: Redirect targets another redirect, creating a cycle

Solution:

// Bad: Creates loop
{ regex: "^/a", replacement: "/b" }
{ regex: "^/b", replacement: "/a" }

// Good: Direct redirects
{ regex: "^/a", replacement: "/c" }
{ regex: "^/b", replacement: "/c" }

Query Strings Lost

Symptoms: Parameters disappear after redirect

Solution: Explicitly capture query strings:

{
  regex: "^/old\\?*(.*)",
  replacement: "/new?$1",
  permanent: true
}

API Reference

Manage redirects programmatically:

// Create redirect
POST /api/trpc/redirects.create
{
  applicationId: "app-123",
  regex: "^/old/(.*)",
  replacement: "/new/$1",
  permanent: true
}

// Update redirect
POST /api/trpc/redirects.update
{
  redirectId: "redirect-456",
  regex: "^/updated/(.*)",
  replacement: "/newer/$1",
  permanent: false
}

// Delete redirect
POST /api/trpc/redirects.delete
{
  redirectId: "redirect-456"
}

// Get redirect details
POST /api/trpc/redirects.one
{
  redirectId: "redirect-456"
}

Regex Reference

Common regex patterns for redirects:

Pattern	Matches	Example
^/path	Starts with /path	/path/to/page
(.*)$	Everything to end	Captures rest of URL
\\d+	One or more digits	123, 2024
\\w+	Word characters	abc, page_1
[^/]+	Anything except /	segment
\\?.*	Query string	?id=123&sort=asc
(a|b)	Either a or b	Matches a or b

Remember to escape special regex characters with double backslashes in JSON/TypeScript: \\. for literal period, \\? for literal question mark.