Tutorial Part 1: Basic Setup

In this tutorial we will build a simple chat server. It will have two pages:

• An index view that lets you type the name of a chat room to join.
• A room view that lets you see messages posted in a particular chat room.

The room view will use a WebSocket to communicate with the Django server and listen for any messages that are posted.

We assume that you have completed our fork of the MDN Django Tutorial so far, and that you have your locallibrary repository: a uv project with manage.py, pyproject.toml, and uv.lock at its root, the locallibrary_config project package, and the catalog app. Every command in this tutorial is run from that root folder.

You can check which version of Django your project uses by running the following command in your terminal:

uv run python -m django --version

Installing Channels and Daphne

Add Channels, together with the Daphne server, to your project:

uv add "channels[daphne]"

Just like uv add "django" did when you set up your project, this records the dependency in pyproject.toml, installs it into .venv, and pins the exact versions in uv.lock. Commit both files.

You can check that they’re installed by running the following command:

uv run python -c "import channels; import daphne; print(channels.__version__, daphne.__version__)"

This tutorial was checked with Channels 4.3.2 and Daphne 4.2.3, on Django 6.1 and Python 3.14.

Redis

This tutorial also uses Docker to install and run Redis. We use Redis as the backing store for the channel layer, which is an optional component of the Channels library that we use in the tutorial. Install Docker from its official website - there are official runtimes for Mac OS and Windows that make it easy to use, and packages for many Linux distributions where it can run natively.

Creating the Chat app

You don’t need to create a project: you already have one. We will put the code for the chat server in its own app, alongside catalog.

Make sure you’re in the same directory as manage.py and type this command:

uv run python manage.py startapp chat

That’ll create a directory chat next to catalog, which is laid out like this:

chat/
    __init__.py
    admin.py
    apps.py
    migrations/
        __init__.py
    models.py
    tests.py
    views.py

For the purposes of this tutorial, we will only be working with chat/views.py and chat/__init__.py. So remove all other files from the chat directory.

After removing unnecessary files, the chat directory should look like:

chat/
    __init__.py
    views.py

We need to tell our project that the chat app is installed. Edit the locallibrary_config/settings.py file and add 'chat' to the end of the INSTALLED_APPS setting, after catalog. Don’t remove anything that’s already there. It’ll look like this:

# locallibrary_config/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Add our new application
    'catalog.apps.CatalogConfig', # This object was created for us in /catalog/apps.py
    'chat',
]

Add the index view

We will now create the first view, an index view that lets you type the name of a chat room to join.

Create a templates directory in your chat directory. Within the templates directory you have just created, create another directory called chat, and within that create a file called index.html to hold the template for the index view.

Your chat directory should now look like:

chat/
    __init__.py
    templates/
        chat/
            index.html
    views.py

Put the following code in chat/templates/chat/index.html:

<!-- chat/templates/chat/index.html -->
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Chat Rooms</title>
    <link rel="icon" href="https://fav.mhciael.com/💬">
</head>

<body>
    <form>
        What chat room would you like to enter?<br>
        <input id="room-name-input" type="text" size="100"><br>
        <button id="room-name-submit" type="submit">Enter</button>
    </form>
    <script>
        document.querySelector('#room-name-input').focus();
        const form = document.querySelector('form');

        form.addEventListener('submit', function (e) {
            e.preventDefault();
            var roomName = document.querySelector('#room-name-input').value;
            window.location.pathname = '/chat/' + roomName + '/';
        });
    </script>
</body>

</html>

Create the view function for the room view. Put the following code in chat/views.py:

# chat/views.py
from django.shortcuts import render


def index(request):
    return render(request, "chat/index.html")

To call the view, we need to map it to a URL - and for this we need a URLconf.

To create a URLconf in the chat directory, create a file called urls.py. Your app directory should now look like:

chat/
    __init__.py
    templates/
        chat/
            index.html
    urls.py
    views.py

In the chat/urls.py file include the following code:

# chat/urls.py
from django.urls import path

from . import views


urlpatterns = [
    path("", views.index, name="index"),
]

The next step is to point the root URLconf at the chat.urls module. Your locallibrary_config/urls.py already imports include() and already includes catalog.urls. Add the chat app in the same style, right after the catalog block:

# locallibrary_config/urls.py
# (after the existing catalog block)
urlpatterns += [
    path('chat/', include('chat.urls')),
]

Leave the admin, catalog, redirect, and static-files entries as they are.

Let’s verify that the index view works. Run the following command:

uv run python manage.py runserver

You’ll see output like the following on the command line:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 29, 2026 - 09:28:06
Django version 6.1.1, using settings 'locallibrary_config.settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Unlike in the original tutorial, you won’t see a warning about unapplied migrations, because you already ran migrate for catalog.

Go to http://127.0.0.1:8000/chat/ 🔗 in your browser and you should see the text “What chat room would you like to enter?” along with a text input to provide a room name. (The site root still redirects to catalog/, so type the /chat/ path yourself.)

Type in “lobby” as the room name and press enter. You should be redirected to the room view at http://127.0.0.1:8000/chat/lobby/ but we haven’t written the room view yet, so you’ll get a “Page not found” error page.

Go to the terminal where you ran the runserver command and press Control-C to stop the server.

Integrate the Channels library

So far we’ve just created a regular Django app; we haven’t used the Channels library at all. Now it’s time to integrate Channels.

Let’s start by creating a routing configuration for Channels. A Channels routing configuration is an ASGI application that is similar to a Django URLconf, in that it tells Channels what code to run when an HTTP request is received by the Channels server.

Start by replacing the contents of the locallibrary_config/asgi.py file with the following code:

# locallibrary_config/asgi.py
import os

from channels.routing import ProtocolTypeRouter
from django.core.asgi import get_asgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "locallibrary_config.settings")

application = ProtocolTypeRouter(
    {
        "http": get_asgi_application(),
        # Just HTTP for now. (We can add other protocols later.)
    }
)

Now add the Daphne library to the list of installed apps, in order to enable an ASGI version of the runserver command.

Edit the locallibrary_config/settings.py file and add 'daphne' to the top of the INSTALLED_APPS setting. It’ll look like this:

# locallibrary_config/settings.py
INSTALLED_APPS = [
    'daphne',
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Add our new application
    'catalog.apps.CatalogConfig', # This object was created for us in /catalog/apps.py
    'chat',
]

You’ll also need to point Daphne at the root routing configuration. Edit the locallibrary_config/settings.py file again and add the following to the bottom of it:

# locallibrary_config/settings.py
# Daphne
ASGI_APPLICATION = "locallibrary_config.asgi.application"

With Daphne now in the installed apps, it will take control of the runserver command, replacing the standard Django development server with the ASGI compatible version.

Let’s ensure that the Channels development server is working correctly. Run the following command:

uv run python manage.py runserver

You’ll see output like the following on the command line:

Watching for file changes with StatReloader
Performing system checks...

System check identified no issues (0 silenced).
September 29, 2026 - 09:28:06
Django version 6.1.1, using settings 'locallibrary_config.settings'
Starting ASGI/Daphne version 4.2.3 development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Notice the line beginning with Starting ASGI/Daphne …. This indicates that the Daphne development server has taken over from the Django development server.

Go to http://127.0.0.1:8000/chat/ 🔗 in your browser and you should still see the index page that we created before. Your catalog pages at http://127.0.0.1:8000/catalog/ 🔗 still work too: Daphne serves them the same way.

Go to the terminal where you ran the runserver command and press Control-C to stop the server.

This tutorial continues in Tutorial 2.