Skip to content
Daniel Gietmann
← Blog
Coding

Redirecting an old domain without losing links

With go-redirect, a small Docker container, you redirect an abandoned domain including its paths to a new one. Three settings are easy to get wrong.

When a domain is abandoned, bookmarks, links from old posts and entries on Google still hang on it. If you simply let it expire, all of these paths end in an error. A redirect that sends every path to the matching place on the new domain keeps them alive.

My tool for that is go-redirect, a Go program in a Docker container that answers every request with a redirect. It is configured only through a few environment variables. According to the README the image is around 5 MB, a static binary on scratch.

The simple case

One domain should point entirely to another, with all paths:

services:
  redirect:
    image: ghcr.io/danielgtmn/go-redirect:latest
    ports:
      - "80:8080"
    environment:
      - REDIRECT_TARGET=https://neue-domain.de
      - REDIRECT_CODE=301
      - PRESERVE_PATH=true
    restart: unless-stopped

alte-domain.de/blog/artikel?seite=2 then becomes https://neue-domain.de/blog/artikel?seite=2. That only works if the paths on the new site are the same. If you changed slugs during the move, those cases belong in a redirect of their own on the new site.

REDIRECT_CODE knows two values. 301 tells browsers and search engines that the move is permanent, and is the right choice for an abandoned domain. You use 302 as long as you are not sure yet. Any other value falls back to 301 without a message.

Three settings that are easy to get wrong

The first is PRESERVE_PATH. The README states true as the default, but the code only carries over path and query when the variable is exactly true. If it is missing, every request lands on the home page of the target. So always set it explicitly. To visitors that looks like a broken link, and Google gets the same response for every old subpage.

The second is a trailing slash on REDIRECT_TARGET. The path is appended directly to the target. https://neue-domain.de/ plus /kontakt becomes https://neue-domain.de//kontakt. Many servers cope with that, but it is still not pretty. So give the target without a trailing slash.

The third is the scanner block. With BLOCK_SCANNERS=true the container answers typical paths of vulnerability scanners with 404, for example .env, wp-admin or phpmyadmin. It compares substrings in the path, ignoring case. The list also contains general words such as admin, backup, debug, trace or graphql and extensions such as .php. An old article at /blog/backup-strategie would therefore get a 404 instead of a redirect. Go through your old URLs against the list once. If something does not fit, you create your own JSON file and mount it through BLOCKED_PATHS_FILE or as a volume at /scanner_paths.json.

Taking subdomains along

If the old domain has subdomains, a single target is not enough. For that there is REDIRECT_DOMAIN_MAP in the format quelle:ziel:

docker run -d \
  -p 80:8080 \
  -e REDIRECT_DOMAIN_MAP=alte-domain.de:neue-domain.de \
  ghcr.io/danielgtmn/go-redirect:latest

Then blog.alte-domain.de/post becomes the address https://blog.neue-domain.de/post. Path and query are always preserved in this mode, regardless of PRESERVE_PATH. The scheme comes from REDIRECT_SCHEME and defaults to https. Hosts that do not match the source get a 404, unless you additionally set REDIRECT_TARGET as a catch-all target.

TLS comes from the proxy

go-redirect only speaks HTTP, on port 8080 by default. But anyone who requests https://alte-domain.de needs a valid certificate for the old domain, otherwise they see a certificate warning before the redirect even takes effect. That is handled by the reverse proxy in front of the container, in Coolify for example Caddy or Traefik.

The same order applies there as for any new hostname: DNS first, then enter the domain in the proxy. I described why in the post about Hindsight on Coolify. In short, the proxy otherwise requests certificates it cannot validate and runs into the Let's Encrypt rate limit.

Logs without IP addresses

Every redirect ends up as a line in the log, with method, path and target. The container replaces the IP address completely with x.x.x.x or x:x:x:x:x:x:x:x. So you see which old paths are still being requested without collecting personal data. With LOG_LEVEL=none you switch the lines off entirely.

For a healthcheck there is /health, which answers with OK. This one path is therefore never redirected.

Checking it works

A call with curl -I shows status code and target without following the redirect:

curl -I "https://alte-domain.de/blog/artikel?seite=2"

The response should contain 301 and a Location line with the complete new address, path and query included. If it only shows the home page, PRESERVE_PATH=true is missing.

For Google, the change of address in the Search Console is worth doing afterwards. It requires that both domains are verified there and the 301 redirects are already in effect. You can switch the container off once no old paths show up in the log over a longer period.

Common questions

How do I redirect an old domain with all its paths to a new one?
With go-redirect you set REDIRECT_TARGET to the new domain, REDIRECT_CODE=301 and PRESERVE_PATH=true. Then path and query are preserved. That only works if the paths on the new site are the same.
301 or 302 for an abandoned domain?
301 tells browsers and search engines that the move is permanent, and is the right choice for an abandoned domain. You use 302 as long as you are not sure yet. In go-redirect, any other value in REDIRECT_CODE falls back to 301 without a message.
Why does every request land on the home page with go-redirect?
Then PRESERVE_PATH=true is missing. The README states true as the default, but the code of go-redirect only carries over path and query when the variable is exactly true. So always set it explicitly.
Does the old domain still need a TLS certificate after the move?
Yes. Anyone who requests the old domain over https needs a valid certificate for it, otherwise they see a certificate warning before the redirect takes effect. go-redirect only speaks HTTP, the certificate is handled by the reverse proxy in front of the container.