Live demo: django-hostmap

The routing under every link on this site

django-hostmap is the substrate for this whole demo network: it routes requests to per-package hosts from one codebase, and it is the reason every link between them just works, whether it stays on this host or jumps to another.

Full package: install, docs, changelog

Package: django-hostmap
This host: hostmap.icvoss.com
Default entry: www
Scheme: https

The resolved host map

This is a live rendering of what manage.py hostmap prints on this server right now: every entry in the HOSTMAP setting, its effective host, and whether it routes, redirects, or wildcards.

$ python manage.py hostmap hostmap.icvoss.com

Parent domain: icvoss.com Scheme: https Port: (none)

www *default* host: www.icvoss.com urlconf: icvoss.urls_www

hostmap host: hostmap.icvoss.com urlconf: icvoss.urls_hostmap

tree host: tree.icvoss.com urlconf: icvoss.urls_tree

taxonomy host: taxonomy.icvoss.com urlconf: icvoss.urls_taxonomy

search host: search.icvoss.com urlconf: icvoss.urls_search

sitemaps host: sitemaps.icvoss.com urlconf: icvoss.urls_sitemaps

brickwork host: brickwork.icvoss.com urlconf: icvoss.urls_brickwork

apex www

Every link below is a live reverse()

No link on this page is a hard-coded URL. Each one is the output of a plain Django url template tag; hostmap decides, per call, whether the result stays relative or becomes absolute.

Show absolute URLs for every link (reveal what reverse() returns even for same-host links)

Cross-host Open the django-icv-tree demo https://tree.icvoss.com/ {% url 'tree_demo' %} -> resolves on the "tree" entry

Cross-host Open the django-icv-taxonomy demo https://taxonomy.icvoss.com/ {% url 'taxonomy_demo' %} -> resolves on the "taxonomy" entry

Cross-host Open the django-icv-search demo https://search.icvoss.com/ {% url 'search_demo' %} -> resolves on the "search" entry

Cross-host Open the django-icv-sitemaps demo https://sitemaps.icvoss.com/ {% url 'sitemaps_demo' %} -> resolves on the "sitemaps" entry

Cross-host Open the django-brickwork demo https://brickwork.icvoss.com/ {% url 'brickwork_landing' %} -> resolves on the "brickwork" entry

Same-host Jump to the resolved map above /#map-section (relative, this page) {% url 'hostmap_demo' %}#map-section -> same entry as current request

Same-host How django-hostmap works /how/ (relative, second page on this host) {% url 'hostmap_how' %} -> same entry as current request, byte-identical to stock Django (BR-003)

Compare the two "Same-host" rows above with any "Cross-host" row: same-host links, including the one to the /how/ page, stay relative because hostmap leaves them untouched; only cross-host links are rewritten absolute.

How this works, in three steps

Middleware routes the request

HostmapMiddleware matches request.get_host() against the map and sets request.urlconf. This request landed on the "hostmap" entry's URLconf because you asked for this host.

reverse() gets host-aware

A patched resolver retries other entries' URLconfs on NoReverseMatch. Same-host names resolve exactly as stock Django always has, byte-identical.

Cross-host becomes absolute

When the match lands on a different entry, the result comes back as a full URL with scheme and host, so the link works regardless of which subdomain rendered the page.

The two edge cases that matter

Named acceptance criteria for hostmap, demonstrated rather than described.

Redirect entry

The apex domain (icvoss.com, no subdomain) is a redirect entry, not a routed one. It 301s to the default entry preserving path and query string.

$ curl -I https://icvoss.com:(none)/
> 301 Moved Permanently
> Location: https://www.icvoss.com:(none)/

Wildcard subdomain

The "preview" entry matches any single subdomain level not claimed by another entry. This demo network uses it to show wildcard capture, exposed as request.hostmap.subdomain.

$ curl https://pr-482.icvoss.com:(none)/
> request.hostmap.label == "preview"
> request.hostmap.subdomain == "pr-482"

What happens on a host nobody declared?

Not every possible subdomain is in the resolved map above. HOSTMAP_UNMATCHED decides what happens when a request arrives for a host that is not.

This site: fail open (default)

With HOSTMAP_UNMATCHED = "default" (also the setting's own default, so most deployments get this for free), an unmapped host is not an error: it falls through to the default entry (www), and the visitor lands on the main site exactly as if they had typed it directly.

$ curl -I https://anything.icvoss.com/
> 200 OK
> served by the "www" entry, no error

Try it yourself: pick any subdomain that is not one of the demo hosts above, for example https://anything.icvoss.com/, and you will land on the main site. That is the fail-open default in action, not a fallback error page.

The alternative: reject

Setting HOSTMAP_UNMATCHED = "reject" instead makes an unmapped host a hard 404: no fallback, no guessing which entry the visitor probably meant. This site does not use it; every subdomain it does not recognise is meant to still resolve to something useful.

$ curl -I https://anything.icvoss.com/
> 404 Not Found (only with HOSTMAP_UNMATCHED = “reject”, not this site)

Other live demos

django-hostmap (you are here)

Host-based URL routing and host-aware reversing.