DEV Community

Stanislav Tonkich
Stanislav Tonkich

Posted on

Website Relaunch Without Losing Rankings: Redirect Mapping and a Bash Launch Test

A relaunch changes your URLs, and search engines and visitors still use the old ones. If those old URLs return 404, you lose the traffic and the signals that took years to build. The fix is not complicated, but it needs to be done in a careful order and tested before launch day.

In this tutorial you will build a URL inventory of the old site, write a mapping table, turn it into an nginx map, and test every row with a Bash script. You will also get a pre-launch checklist and a short monitoring plan for the first days after launch.

Prerequisites: shell access, curl, an nginx server for the new site, and a list of your old URLs.

Step 1: Build the URL inventory

Start from what exists, not from what you remember. Combine several sources:

  • The XML sitemap of the old site.
  • A crawl of the old site with a crawler of your choice, exported as CSV.
  • URLs with traffic or backlinks from your analytics, Search Console and a backlink tool.

Merge them into one file, one URL per line, and remove duplicates:

cat sitemap_urls.txt crawl_urls.txt analytics_urls.txt \
  | sed 's/[?#].*$//' \
  | sort -u > old_urls.txt
wc -l old_urls.txt
Enter fullscreen mode Exit fullscreen mode

The sed line strips query strings and fragments. If your site uses query strings for real content (for example ?id=12), keep them and handle them separately.

Step 2: Create the mapping table

For each old URL, decide what happens:

  • 301: the content has a new home. Redirect to the closest matching new page.
  • 410: the content is gone for good and has no equivalent. Tell search engines so.
  • Keep: the URL stays the same, no rule needed.

Use a simple CSV with three columns, old_path,new_path,status:

/leistungen/seo.html,/services/seo/,301
/blog/2019/old-post,/blog/old-post/,301
/impressum.html,/imprint/,301
/aktion-2018,,410
Enter fullscreen mode Exit fullscreen mode

Rules for good mapping:

  1. Redirect to the most relevant page, not to the homepage. Mass redirects to the homepage are often treated like soft 404 errors.
  2. Point directly to the final URL. Avoid chains such as A to B to C.
  3. Keep a note why each 410 is a 410.

Step 3: Turn the table into an nginx map

nginx can read a map block and apply it with one if-free rule. First generate the map file from the CSV:

awk -F, '$3==301 {printf "    %s %s;\n", $1, $2}' mapping.csv > redirects_301.inc
awk -F, '$3==410 {printf "    %s 1;\n", $1}' mapping.csv > gone_410.inc
Enter fullscreen mode Exit fullscreen mode

Then use the two include files in your configuration:

map $uri $redirect_target {
    default "";
    include /etc/nginx/redirects_301.inc;
}

map $uri $is_gone {
    default 0;
    include /etc/nginx/gone_410.inc;
}

server {
    listen 80;
    server_name example.com;

    if ($is_gone) {
        return 410;
    }

    if ($redirect_target) {
        return 301 $redirect_target;
    }

    # normal site config follows
}
Enter fullscreen mode Exit fullscreen mode

Using if only to return is a safe use in nginx. Keep the map entries exact: a path in the map must match $uri exactly, including the trailing slash. Run nginx -t before you reload.

Step 4: Test every row with Bash

Do not trust the table, test it. This script requests each old path on the staging host and compares the status code and the redirect target:

#!/usr/bin/env bash
# usage: ./test_redirects.sh https://staging.example.com mapping.csv
base="$1"
file="$2"
fail=0

while IFS=, read -r old new status; do
  [ -z "$old" ] && continue
  result=$(curl -s -o /dev/null -w "%{http_code} %{redirect_url}" "$base$old")
  code=${result%% *}
  target=${result#* }

  if [ "$code" != "$status" ]; then
    echo "FAIL $old: expected $status, got $code"
    fail=1
  elif [ "$status" = "301" ] && [ "$target" != "$base$new" ]; then
    echo "FAIL $old: expected target $base$new, got $target"
    fail=1
  fi
done < "$file"

[ "$fail" -eq 0 ] && echo "All rows OK" || exit 1
Enter fullscreen mode Exit fullscreen mode

Also check for chains: every 301 target must itself return 200 and not another redirect.

awk -F, '$3==301 {print $2}' mapping.csv | sort -u | while read -r p; do
  code=$(curl -s -o /dev/null -w "%{http_code}" "https://staging.example.com$p")
  [ "$code" != "200" ] && echo "Target $p returns $code"
done
Enter fullscreen mode Exit fullscreen mode

Run both scripts until they print nothing but "All rows OK".

Step 5: Pre-launch checklist

  • The staging site is blocked from indexing (password or noindex), and the production site is not.
  • Remove the staging noindex and any Disallow: / from robots.txt on launch day.
  • Canonical tags on the new pages point to the new production URLs.
  • The new XML sitemap lists only URLs that return 200.
  • Internal links use the new URLs directly, not the redirects.
  • Redirects and 410 rules are active and tested.
  • Analytics and Search Console are set up for the new site.

The two most expensive mistakes are launching with the staging noindex still in place and launching with a robots.txt that blocks everything. Check both manually in the browser source and at /robots.txt right after go-live.

Step 6: Monitor the first 72 hours

After launch, check these things at set times (right after launch, after 24 hours, after 72 hours):

  1. Search Console, page indexing report: watch for a rise in "Not found (404)" and "Page with redirect".
  2. Search Console, sitemaps: confirm the new sitemap was read without errors.
  3. Server logs: list the most requested URLs that return 404.
awk '$9 == 404 {print $7}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head -20
Enter fullscreen mode Exit fullscreen mode

Each URL in this list is either a missing row in your mapping or a broken internal link. Add the missing redirects, rerun the test script, reload nginx.

Expect some ranking movement in the first weeks. A clean 301 mapping lets the signals move to the new URLs, but search engines need time to process it. Do not change the structure again in this period.

Summary

Build the inventory from several sources, map each URL to a 301 or a 410, generate the nginx maps from one CSV, and test every row with a script before launch. The CSV is your single source of truth, and the test script is your safety net.

Top comments (0)