jasny/dns-redirect repository overview

⁠DNS Redirect Service

The redirect service allows you to configure a domain to automatically redirect to a new destination based on CNAME records. By adding a CNAME record to your DNS, you can specify the target domain for redirection and indicate the type of HTTP status code to be used.

⁠Features

• Redirects requests based on CNAME records.
• Supports multiple types of HTTP status codes (301, 302, 303, 307, 308).
• DNS configuration can be customized using /etc/resolv.conf or overridden via an environment variable.
• Uses Google Public DNS as a fallback if system DNS configuration fails.
• Automatic HTTPS support using Let's Encrypt.

⁠Running the Service

docker run -d \
  -e REDIRECT_DOMAIN_301=redirect.example.com \
  -p 80:80 -p 443:443 \
  -v certs:/var/app/certs \
  jasny/dns-redirect

⁠Environment Variables

⁠Redirect Domains

The service uses environment variables to determine which domains to redirect and with which HTTP status codes. The following environment variables are supported:

• REDIRECT_DOMAIN_301: Domain suffix to be redirected with HTTP status code 301 (Moved Permanently).
• REDIRECT_DOMAIN_302: Domain suffix to be redirected with HTTP status code 302 (Found).
• REDIRECT_DOMAIN_303: Domain suffix to be redirected with HTTP status code 303 (See Other).
• REDIRECT_DOMAIN_307: Domain suffix to be redirected with HTTP status code 307 (Temporary Redirect).
• REDIRECT_DOMAIN_308: Domain suffix to be redirected with HTTP status code 308 (Permanent Redirect).

⁠Other Environment Variables

• DNS_CONFIG_FILE: Path to the DNS configuration file (default: /etc/resolv.conf).
• CACHE_DNS: Whether to cache DNS lookups (default: false).
• HTTP_PORT: Port on which the service listens for incoming HTTP requests (default: 80).
• HTTPS_PORT: Port on which the service listens for incoming HTTPS requests (default: 443).

⁠How It Works

1. The service listens on port 80 and handles incoming HTTP requests and port 443 for HTTPS requests.
2. For each request, it performs a CNAME lookup for the hostname.
3. Based on the CNAME result, it determines if the CNAME ends with one of the configured suffixes (e.g., example.com).
4. If a match is found, the service removes the suffix and redirects the request to the target domain with the appropriate status code.
5. For HTTPS requests an SSL certificate is requested from Let's Encrypt (on the first request of that domain).
6. The scheme (http or https) is preserved from the original request.

⁠Automatic HTTPS support

The redirect service will not modify the schema (http or https) of the request. For HTTPS, a certificate is automatically obtained using Let's Encrypt⁠ on the first request.

⁠Example Usage

• Suppose you have a CNAME record like foo.example.com that points to bar.example.net.permanent-redirect.com.
• If REDIRECT_DOMAIN_301="permanent-redirect.com" is set, and the CNAME matches, the service will remove .permanent-redirect.com and redirect foo.example.com to bar.example.net using a 301 Moved Permanently status code.

⁠Source code

The source code is available under the MIT license at jasny/dns-redirect on GitHub⁠.