How To Use Django-Hosts

Essentially, django-hosts allows you to make different parts of the same Django application accessible on different subdomains. We can imagine addresses like “help.example.com” or “shop.example.com” which would be served by separate applications in a single Django project.

This library facilitates the creation and management of subdomains in Django. Its main advantage is its ease of use. It only takes a few lines of code to start using it. Moreover, these features are very broad.

You can define rules for subdomains, manage specific views, or use regular expressions for more complex patterns. Managing subdomains dynamically using a database is totally possible, even if a modification of your DNS configuration will be necessary.

Setup

The installation of the library is done in a very classic way using pip.

pip install django-hosts

Just add django-hosts to the INSTALLED_APPS list and modify the middlewares by adding HostsRequestMiddleware to the beginning of the MIDDLEWARE list and HostsResponseMiddleware to the end of the same list.

Here, the library is installed and only has to be configured. We define some configuration elements, such as the default subdomain (DEFAULT_HOST) and the root file to use for the rest of the configuration (ROOT_HOSTCONF). The configuration follows the traditional pattern for a Django application.

ROOT_HOSTCONF = "mywebiste.hosts"
DEFAULT_HOST = "www"

We then create the root file targeted previously. To do this, add a hosts.py file in the folder containing your main urls.py. This file must contain the following parameters:

from django.conf import settings
from django_hosts import patterns, host


host_patterns = patterns("",
  host("www", settings.ROOT_URLCONF, name="www"),
)

This basic setup keeps the “www” subdomain running smoothly.

Usage

Let’s say that we have an application called help containing all of the user support pages for our project. There is a list of frequently asked questions/answers, as well as a way to contact support.

To make this subdomain functional, simply add the subdomain to the hosts.py file and indicate the location of the corresponding URLs.

from django.conf import settings
from django_hosts import patterns, host

host_patterns = patterns("",
  host("www", settings.ROOT_HOSTCONF, name="www"),
  host("help", "help.urls", name="help"),
)

django-hosts takes care of managing subdomains during local development, making it easier to test and develop the project.

To test locally, you will need to modify your local DNS. On Linux and macOS, the file to modify is in /etc/hosts. On Windows, the file in question is located in %SystemRoot%\\system32\\drivers\\etc\\hosts.

Here are the few lines to add:

127.0.0.1 localhost
255.255.255.255 broadcasthost
::1 localhost

127.0.0.1 www.mysite.local
127.0.0.1 help.mysite.local

In views, it is always possible to use Django’s reverse() function by adding the subdomain as an argument.

from django.shortcuts import render
from django_hosts.resolvers import reverse


def index(request):
  url = reverse("index", host="www")

  return render(request, "index.html", {"url": url})

More details

To learn more about django-hosts, you can consult the official documentation or take a look at the GitHub repository.