If your development environment also lives in WSL2, this is the setup path I wish I had before the workshop.

The Problem

The workshop instructions were straightforward: install a local model runner, download Gemma, and write a small Python application that talks to the model. The codelab was based on Ollama, which made the Windows-native path look especially simple.

The problem was that my development environment was not on Windows. I use WSL2 for my terminal, Python projects, virtual environments, and Git repositories. LM Studio, however, was installed on the Windows side because that is where the desktop application and model runtime live.

That gives you two environments on one computer:

Windows
└── LM Studio
    └── Gemma model and local HTTP API

WSL2
└── Python application, terminal, files, and virtual environment

The model does not need to be installed twice. The Python application in WSL2 only needs to reach LM Studio's HTTP API.

That sounds simple. It was not obvious from the workshop instructions, and several different problems looked like the same problem:

• The LM Studio chat window worked, but the API server was stopped.
• localhost inside WSL2 was not initially the same as localhost on Windows.
• I entered Windows WSL configuration into a Linux shell.
• The workshop used Ollama model names, while LM Studio returned different model identifiers.
• I spent time investigating a shell plugin that was unrelated to the basic API connection.

The key was separating the layers instead of treating "LM Studio works" as one single test.

My Environment

This was the setup I used:

• Windows 11, build 26200
• WSL version 2.7.11.0
• LM Studio 1.0.7 (build 2)
• 16 GB RAM
• Intel UHD Graphics 620
• WSL2 as the development environment
• Gemma 4 E2B served by LM Studio

Your versions may differ. LM Studio's interface changes, so treat the concepts and verification commands as more important than the exact screenshots.

First Important Distinction: Chat Is Not the API

Being able to ask questions in LM Studio's chat window does not mean that a program can reach the model.

The chat interface and the Local Model API server are separate. In my version of LM Studio, the relevant setting was here. LM Studio also documents this server as an OpenAI-compatible API:

Settings -> Local Model API -> Local API server

The switch must be running before a Python program or curl can connect.

You can check the server from Windows PowerShell:

lms server status --json --quiet
curl.exe http://127.0.0.1:1234/v1/models

The curl.exe spelling matters in PowerShell. curl may resolve to PowerShell's Invoke-WebRequest alias rather than the normal curl executable.

A working response looks like this:

{
  "data": [
    {
      "id": "google/gemma-4-e2b",
      "object": "model",
      "owned_by": "organization_owner"
    }
  ],
  "object": "list"
}

If this Windows-side request fails, do not troubleshoot WSL2 yet. The API server or its port is the problem.

The Setup That Worked

WSL2 commonly starts in NAT networking mode. In that mode, a service running on Windows is not always reachable from Linux through 127.0.0.1. Microsoft's WSL networking documentation describes the difference between the default NAT and mirrored modes.

Windows 11 supports mirrored networking, which lets WSL2 and Windows reach each other's localhost services. That was the simplest option for this setup because LM Studio could continue listening on localhost instead of being exposed to the rest of my network.

Step 1: Configure mirrored networking

Open the WSL configuration file from PowerShell, not from Bash:

notepad.exe "$env:USERPROFILE\.wslconfig"

If the file already exists, add the setting under its existing [wsl2] section. Otherwise, create the file with:

[wsl2]
networkingMode=mirrored

Save the file, then restart WSL from PowerShell:

wsl --shutdown

This was one of my mistakes. I initially pasted the [wsl2] lines into the WSL terminal, where Bash tried to execute them as commands. .wslconfig is a Windows file stored at %UserProfile%\.wslconfig.

Step 2: Start the LM Studio API

Open LM Studio and enable the Local API server switch under Settings -> Local Model API.

The default port is usually 1234. If you use another port, replace 1234 in every command and code sample below.

Confirm the server from PowerShell before testing from WSL:

lms server status --json --quiet
curl.exe http://127.0.0.1:1234/v1/models

Step 3: Test from WSL2

Open a new WSL terminal and run:

curl --connect-timeout 5 http://127.0.0.1:1234/v1/models

The response should contain the same model list as the PowerShell request.

At this point, the important test has passed: a program running inside WSL2 can reach a model server running on Windows.

What About NAT Networking?

Mirrored networking is not the only solution.

With the default NAT configuration, WSL2 can reach the Windows host through the gateway address shown by this command:

LM_STUDIO_HOST="$(ip route show default | awk '$1 == "default" {print $3; exit}')"
echo "$LM_STUDIO_HOST"

LM Studio must then listen beyond Windows localhost:

lms server start --port 1234 --bind 0.0.0.0

From WSL2, the request becomes:

curl "http://${LM_STUDIO_HOST}:1234/v1/models"

This approach has two drawbacks:

1. The WSL2 gateway address can change after a restart.
2. Binding to 0.0.0.0 exposes the server beyond localhost, so authentication and firewall rules become important.

NAT is still useful when you want stronger network separation or do not want to change the global WSL networking mode. For this single-computer setup, mirrored networking was simpler and allowed LM Studio to remain local-only.

Adapting the Workshop Code

The workshop example uses Ollama. Its Python client and model name assume an Ollama server:

import ollama

response = ollama.chat(
    model="gemma4:e2b",
    messages=[{"role": "user", "content": prompt}],
)

LM Studio provides an OpenAI-compatible API, so the same application can use the OpenAI Python client instead.

Create a small project with uv:

mkdir gemma4-local-app
cd gemma4-local-app
uv init
uv add openai==2.53.0

uv creates and manages the project environment and resolves the Python dependencies. There is no separate virtual-environment setup to maintain.

Create app.py:

import os

from openai import OpenAI


MODEL = os.getenv("LM_STUDIO_MODEL", "google/gemma-4-e2b")
BASE_URL = os.getenv("LM_STUDIO_BASE_URL", "http://127.0.0.1:1234/v1")
API_KEY = os.getenv("LM_STUDIO_API_KEY", "lm-studio")

client = OpenAI(
    base_url=BASE_URL,
    api_key=API_KEY,
)


def ask_model(prompt: str) -> str:
    response = client.chat.completions.create(
        model=MODEL,
        messages=[{"role": "user", "content": prompt}],
    )
    return response.choices[0].message.content or ""


if __name__ == "__main__":
    print(ask_model("Give me three creative local AI app ideas."))

Run it from WSL2:

uv run app.py

The model stays loaded in LM Studio on Windows. The Python process, source code, and uv environment remain in WSL2.

No API token is needed when LM Studio authentication is disabled. The lm-studio value in the example is only a non-empty placeholder required by the OpenAI client; I did not create or enter a token. If you enable authentication in LM Studio, replace it with a real token:

export LM_STUDIO_API_KEY="your-token"

Do not commit that token to the repository.

Use the Model Identifier LM Studio Returns

The workshop's gemma4:e2b is an Ollama-style model tag. It is not necessarily the identifier that LM Studio expects.

Always inspect the API response:

curl http://127.0.0.1:1234/v1/models

In my case, the correct identifier was:

google/gemma-4-e2b

Use that exact value in the OpenAI client. Do not guess the model name from the chat display or from another model runner's documentation.

The Failures That Cost Me Time

The API server was stopped

My LM Studio chat session was working, but the Local Model API screen showed Stopped. No WSL networking configuration can fix a server that is not listening.

The first diagnostic should always be the Windows-side request:

curl.exe http://127.0.0.1:1234/v1/models

I used the wrong localhost

Under default WSL2 NAT networking, 127.0.0.1 inside WSL2 refers to the Linux environment. It does not automatically mean the Windows host.

Mirrored networking changes this relationship so WSL2 can reach Windows localhost services through 127.0.0.1.

I entered a Windows configuration file into Bash

These lines are not Bash commands:

[wsl2]
networkingMode=mirrored

They belong in %UserProfile%\.wslconfig, and the WSL subsystem must be restarted after saving them.

I investigated the wrong plugin

I also tried to install a shell-access plugin for LM Studio. That plugin is designed to let a model execute commands on the host or in WSL. It does not solve the basic problem of making a Python program reach the model API.

For workshop code, the API connection is the first milestone. Tool execution and agent plugins are a separate concern.

A Note on Performance

Connectivity and inference speed are different problems.

After the connection worked, Gemma 4 E2B generated at roughly 2.8 to 3.3 completion tokens per second on my laptop. A simple coding request took several minutes because the model spent many tokens on reasoning and the machine had no discrete GPU.

That does not indicate a WSL2 networking failure. If /v1/models responds quickly but generation is slow, the connection is working. The likely causes are model size, reasoning behavior, quantization, context length, and available hardware.

For a workshop, benchmark a small non-reasoning or coding-focused model before assuming that the API setup is broken.

The Checklist I Wish I Had

Before the workshop, I would have run these checks in order:

1. Start the model in LM Studio.
2. Enable Settings -> Local Model API -> Local API server.
3. Confirm the API from PowerShell with curl.exe.
4. Configure mirrored networking in %UserProfile%\.wslconfig.
5. Run wsl --shutdown from PowerShell.
6. Confirm the same API from WSL2 with curl.
7. Copy the exact model ID from /v1/models.
8. Use an OpenAI-compatible client from the WSL2 application.
9. Only after all of that, investigate tool calling or agent behavior.

The entire distinction is this:

LM Studio chat working
        !=
LM Studio API reachable from WSL2

Once I treated those as separate systems, the setup became straightforward.

If you use Windows for your model runtime and WSL2 for development, I hope this saves you the day I lost.

¡Hasta luego!

The Problem

A shipping group links a set of cities to a delivery zone. The model is straightforward:

class ShippingGroup(models.Model):
    name = models.CharField(max_length=255)
    country = models.ForeignKey(Country, on_delete=models.CASCADE)
    cities = models.ManyToManyField(City)

When an admin creates a new shipping group, the endpoint needs to validate that none of the selected cities already belong to a competing group in the same region. The original code did this with a triple-nested loop:

for storefront in storefronts:
    for state in states:
        for city in cities:
            if ShippingGroup.objects.filter(
                company=self.company, storefronts=storefront,
                country=country, states=state, cities=city
            ).exists():
                raise ParseError("A shipping group already covers this city.")

For 5 storefronts, 10 states, and 100 cities, that's 5 × 10 × 100 = 5,000 individual .exists() queries. Just to validate the write hasn't even happened yet. And when the validation passes, the write itself used .add():

shipping_group.cities.add(*city_ids)

Under the hood, .add() first issues a SELECT to find which IDs don't already exist in the junction table, then issues a single INSERT for the remaining rows. Neither step is batched: the deduplication query grows to match the full ID set, and the single large INSERT can lock the table. For 5,000 cities, the SELECT + INSERT plus the 5,000 validation queries made the request timeout long before it finished.

The Solution

Three pieces: validate with in-memory set intersection instead of per-row queries, write directly to the .through table in batches, and offload past a threshold to a background task.

Step 1: Validate with set intersection, not per-row .exists()

Instead of checking each city against each existing group one query at a time, fetch all potentially conflicting groups in one query with a Prefetch that hoists the related IDs onto each instance. Then intersect locally:

from django.db.models import Prefetch

def validate_no_overlap(country, storefront_ids, state_ids, city_ids):
    # Fetch every group that might conflict, with all related IDs attached
    existing = ShippingGroup.objects.filter(
        country=country,
    ).prefetch_related(
        Prefetch(
            "storefronts",
            queryset=Storefront.objects.only("id"),
            to_attr="prefetched_storefronts",
        ),
        Prefetch(
            "states",
            queryset=State.objects.only("id"),
            to_attr="prefetched_states",
        ),
        Prefetch(
            "cities",
            queryset=City.objects.only("id"),
            to_attr="prefetched_cities",
        ),
    )

    request_storefronts = set(storefront_ids)
    request_states = set(state_ids)
    request_cities = set(city_ids)

    for group in existing:
        group_sfs = {sf.id for sf in group.prefetched_storefronts}
        group_sts = {st.id for st in group.prefetched_states}
        group_cts = {ct.id for ct in group.prefetched_cities}

        if (
            request_storefronts & group_sfs
            and request_states & group_sts
            and request_cities & group_cts
        ):
            raise ValidationError(
                f"A shipping group already covers this region."
            )

One query to fetch the groups, one query per Prefetch for the related IDs. Typically 3 to 5 queries total regardless of how many storefronts, states, or cities are being checked. The intersection runs entirely in Python, where a set membership check is O(1).

The to_attr on each Prefetch is the key detail: it hoists the filtered queryset onto each ShippingGroup instance as a plain list of objects (prefetched_storefronts, etc.), rather than leaving it as a lazily-evaluated queryset that would re-query on access. The set comprehensions then extract just the IDs for intersection.

Step 2: Write to the .through table directly

.add() looks like a bulk operation, but Django's Many-to-Many manager inserts rows one at a time. For a large set of IDs, the correct approach is to go directly to the auto-generated through model and use bulk_create:

through_model = ShippingGroup.cities.through
batch_size = 500

for i in range(0, len(city_ids), batch_size):
    chunk = city_ids[i : i + batch_size]

    # Verify these IDs actually exist in the database before inserting
    valid_ids = set(
        City.objects.filter(id__in=chunk, country=country_id)
        .values_list("id", flat=True)
    )

    objs = [
        through_model(shippinggroup_id=group_id, city_id=cid)
        for cid in valid_ids
    ]
    through_model.objects.bulk_create(objs, ignore_conflicts=True)

Three things happening here:

• Batching in chunks of 500 keeps the transaction size bounded and prevents a single massive INSERT from locking the table for too long.
• ignore_conflicts=True skips rows that already exist: no duplicate-key error, no need to pre-filter existing relations. If a city is already assigned to this group, the insert is silently ignored.
• Pre-validating IDs against the database (City.objects.filter(id__in=chunk)) ensures you're not inserting garbage IDs that would fail a foreign key constraint. It's one query per batch, not one per row.

For 5,000 cities, that's 10 batches × 2 queries each = 20 queries instead of 5,000 inserts.

Step 3: Offload past a threshold to a background task

Even with batched bulk writes, processing 10,000+ rows synchronously will make the HTTP request hang. At some size, the operation belongs in a queue:

THRESHOLD = 500

def create_shipping_group(data):
    group = ShippingGroup.objects.create(name=data["name"], country=country)

    city_count = len(data["city_ids"])
    if city_count > THRESHOLD:
        assign_cities_to_group.delay(
            city_ids=data["city_ids"],
            country_id=country.id,
            group_id=group.id,
        )
    else:
        # Small enough — do it inline. At this count the SELECT + INSERT
        # in .add() is fast enough and keeps the code simpler.
        cities = City.objects.filter(id__in=data["city_ids"], country=country)
        group.cities.add(*cities.values_list("id", flat=True))

    return group

Below 500 cities: synchronous .add() is fine. Above 500: a Celery task takes over, the request returns immediately with the group created but cities still being assigned in the background. The task uses the same batched bulk_create path from Step 2.

Threshold choice matters: 500 was picked because it's well under a typical request timeout even with a slow database, but it's a number you should tune against your own infrastructure.

Why This Works

Validation is constant-time relative to the input size. The Prefetch queries are bounded by the number of existing groups in the country, not the number of cities being validated. Set intersection is O(n) in Python and negligible at typical group counts.

.through + bulk_create skips the deduplication penalty and avoids table locks. Under the hood, .add() runs a large SELECT to find which IDs are already in the table, then issues one giant INSERT for the rest — both unbounded operations. With ignore_conflicts=True, bulk_create skips the deduplication step entirely, and batching keeps the transactions small enough to avoid locking.

ignore_conflicts means idempotent writes. You can retry the Celery task without worrying about partial progress from a previous attempt. Rows that were already inserted in a prior batch are silently skipped on retry.

The threshold keeps the API responsive. Synchronous for small inputs (the common case), asynchronous for large ones without changing the interface. The caller always gets the same response shape. The group exists, cities are either assigned or being assigned.

Design Decision: The .through Model Changes What You're Responsible For

Using through_model.objects.bulk_create() instead of group.cities.add() means you're bypassing Django's Many-to-Many manager entirely. That's the point: the manager isn't designed for batch writes. But it also means you lose two things the manager normally gives you for free:

• Signal dispatch. .add() fires m2m_changed signals that might be expected by other parts of the system (audit logs, cache invalidation). Writing to the through table directly does not. If those signals matter, you need to fire them manually or postpone logging to a post-write step.
• Validation. The manager checks that the related object exists before inserting. Step 2 compensates with an explicit City.objects.filter(id__in=chunk) pre-check. If you skip that check and insert a non-existent ID, you get a ForeignKeyViolation in Postgres instead of a clean Django error.

Neither of these is a bad trade. Just a trade you should know you're making.

The Result

The validation step went from 5,000 queries — one per city-state-storefront combination — to about 5 regardless of input size. The write went from a single large INSERT with no batching to 10 batched chunks of 500 with idempotent conflict handling, or a background task for counts above the threshold.

The pattern (validate with set intersection, write to .through in batches, offload past a threshold) applies to any Django model with a large Many-to-Many field: tags, categories, user teams, regional assignments, or anywhere else you're adding hundreds or thousands of rows to a junction table.

How are you handling large Many-to-Many writes in your Django apps? Are you going through the through table directly, or have you found a different approach? Drop it in the comments.

¡Hasta luego!

The Problem

You store your timestamps in UTC. Django recommends it, Postgres defaults to it, and it keeps your data unambiguous. Order 582 was placed at 2025-03-10 23:15:00+00:00. Clean, portable, no ambiguity.

But a report that asks for "Tuesday's orders" needs to know what Tuesday means. Tuesday in Lagos starts at 11 PM Monday UTC. Tuesday in London starts at midnight UTC. If your reporting query uses UTC midnight for everyone, orders placed between 11 PM and midnight UTC get assigned to the wrong day for every store east of GMT.

The fix is deceptively simple: each store knows its timezone, and the reporting query converts the store's local day-bounds into a UTC range before filtering. But there's a landmine in the conversion, and it's one that only fires in production:

>>> import pytz, datetime
>>> store_tz = pytz.timezone("Africa/Lagos")
>>> start = datetime.datetime(2025, 3, 10, 0, 0, 0)
>>> store_tz.localize(start)
datetime.datetime(2025, 3, 10, 0, 0, tzinfo=<DstTzInfo 'Africa/Lagos' WAT+1:00:00 STD>)

That worked. But then the code runs again, maybe from a Celery retry, maybe from a helper that already called make_aware, and the datetime is already offset-aware:

>>> aware_start = store_tz.localize(start)     # fine
>>> store_tz.localize(aware_start)             # BOOM
ValueError: Not naive datetime (tzinfo is already set)

The same line fails because pytz.localize() refuses to touch an already-aware datetime. This didn't surface in development because the call path never produced an aware datetime in the dev environment, but in production, with re-queued tasks and retried jobs, it did.

The root cause isn't the localize() call itself: it's that an aware datetime reached the function at all. Guard the input before it hits datetime.combine(), and localize() never sees an aware value. The fix is one guard at the top of the function, and the lesson is that timezone-correct reporting needs both the right model and the right conversion hygiene.

Note on modern Django: The ValueError above is a pytz-specific quirk. Django 4.0 deprecated pytz in favour of Python's built-in zoneinfo, and Django 5.0 removed pytz support entirely. With zoneinfo you use datetime.replace(tzinfo=tz) instead of .localize(), which behaves differently. The code in this article uses pytz because the bug originated in a legacy codebase, and millions of Django apps are still in that position. But the underlying trap is the same regardless of library: passing an aware datetime that carries a UTC date into a function expecting to produce local midnight bounds will silently fetch the wrong day's data if you aren't guarding your inputs.

The Solution

Two pieces: a per-store timezone field, and a helper that safely turns a local calendar date into a UTC range for filtering.

Step 1: Give each store a timezone

# models.py
class Store(models.Model):
    name = models.CharField(max_length=255)
    timezone = models.CharField(
        max_length=50,
        default="Africa/Lagos",
        help_text="IANA timezone name, e.g. 'Africa/Lagos', 'Europe/London'.",
    )

One field. The Lagos store has "Africa/Lagos", the London store has "Europe/London". If a store never sets one, the default keeps it working (and wrong for anyone who notices, which is better than crashing).

Step 2: Convert local day-bounds to a UTC range

The reporting query needs a UTC start and end for the store's local day. A helper handles the conversion safely:

import pytz
from datetime import date, datetime, time, timedelta
from django.utils import timezone as dj_timezone

def local_day_bounds_utc(store_tz: str, target_date: date | datetime) -> tuple[datetime, datetime]:
    """Return (utc_start, utc_end) for the store's local calendar day."""
    tz = pytz.timezone(store_tz)

    # Normalize the date input — if an aware datetime arrives from a
    # Celery retry or pre-processed helper, extract the calendar date
    # in the store's own timezone.
    #
    # This matters because an aware datetime carries a UTC date component,
    # not a local one. A Lagos store at 11:30 PM local time is already the
    # next calendar day in UTC — passing that directly to datetime.combine()
    # would silently produce bounds for the wrong day.
    if isinstance(target_date, datetime) and not dj_timezone.is_naive(target_date):
        target_date = target_date.astimezone(tz).date()

    naive_start = datetime.combine(target_date, time.min)
    naive_end = datetime.combine(target_date + timedelta(days=1), time.min)

    aware_start = tz.localize(naive_start)
    aware_end = tz.localize(naive_end)

    return aware_start.astimezone(pytz.UTC), aware_end.astimezone(pytz.UTC)

naive_end is built as the start of the next day rather than time.max on the current day. This avoids microsecond edge cases on the upper boundary. The next day's midnight is unambiguous. For March 11 and a Lagos store, the UTC range becomes 2025-03-10 23:00+00:00 to 2025-03-11 23:00+00:00. That's Lagos-Tuesday in UTC.

Step 3: Filter with the UTC range

The reporting query now reads cleanly:

from django.db.models import Sum

store = Store.objects.get(id=store_id)
store_tz = pytz.timezone(store.timezone)
target_date = datetime.now(store_tz).date() - timedelta(days=1)  # yesterday, store-local

utc_start, utc_end = local_day_bounds_utc(store.timezone, target_date)

orders = Order.objects.filter(
    store=store,
    created_at__gte=utc_start,
    created_at__lt=utc_end,
)
totals = orders.aggregate(total=Sum("amount"))

One query, timezone-correct by construction. "Yesterday" is derived in the store's own timezone, not the server's. The function converts to UTC once, and the database does the rest.

Why This Works

The conversion is a pure function of data you already have. The store's timezone is a column on the store model. No API calls, no user-preference lookups, no frontend involvement. The reporting query just reads the field and does the math.

Postgres handles the UTC comparison natively. created_at is a timestamptz column, which stores everything as UTC internally. When Django passes two UTC-aware datetimes to __gte/__lt, Postgres can resolve the range with a plain index scan on the created_at column: no timezone arithmetic per row, no sequential scan. The conversion happens once per query, in Python. The database just compares two UTC values.

It works for any date, not just "yesterday." The helper takes a date, not a relative expression. Daily EOD reports, weekly summaries, arbitrary date-picker queries. All call the same function.

Design Decision: Put the Guard on the Input, Not the Output

The local_day_bounds_utc helper normalizes its input before doing anything else. datetime.combine() takes a date and a time. If you pass an aware datetime as the date argument, Python uses its date component, which is the UTC date, not the store-local date. A Lagos store at 11:30 PM local time on March 10 is already March 11 in UTC. Pass that aware datetime directly to combine and you silently get bounds for the wrong day, with no error raised.

In production, the input sometimes isn't a plain date. A Celery task retries and the retry wrapper has already called make_aware on the parameter. A helper upstream pre-processed the date into UTC. The isinstance + is_naive check at the top of the function catches this: if the incoming value is an aware datetime, it's converted to the store's own timezone first, and only the local calendar date is extracted. This means "yesterday" is always resolved in the store's timezone, regardless of what timezone the parameter arrived with.

The lesson: timezone correctness has two layers. The model (which timezone applies) and the conversion hygiene (is the input naive or aware, and does it carry the right date?). You need both. The second layer fails silently in every environment except the one where retries and re-queues happen.

The Result

The daily sales report now returns correct totals for every store, regardless of timezone. Adding a new store in a new city is one field change on the store record. The reporting query picks it up automatically. The input guard means the report produces correct results even when a date parameter arrives through an unexpected code path.

How are you handling per-store or per-tenant timezone-aware reporting? Are you doing it at the DB level, in Python, or have you found a third approach? I'd love to hear what's worked for you in the comments.

¡Hasta luego!

The Problem

GenericForeignKey lets one table point at rows in multiple other tables without knowing which one at query time. The classic use case is an audit log, a notification feed, or a tagging system where the set of target types is open-ended.

But select_related and prefetch_related can't traverse a GFK. The ORM needs to know the target table ahead of time, and a content_type_id/object_id pair doesn't give it that until runtime. The result: every time you touch the GFK on an instance, you pay a query.

Take an activity log. One table, every row references some target: an order, a user, a product:

# models.py
from django.contrib.contenttypes.fields import GenericForeignKey, GenericRelation
from django.contrib.contenttypes.models import ContentType
from django.db import models

class ActivityLog(models.Model):
    actor = models.ForeignKey("User", on_delete=models.CASCADE)
    action = models.CharField(max_length=50)           # "created", "updated", "deleted"
    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
    object_id = models.CharField(max_length=255)
    target = GenericForeignKey("content_type", "object_id")
    created_at = models.DateTimeField(auto_now_add=True)

class Order(models.Model):
    number = models.CharField(max_length=20)
    status = models.CharField(max_length=20)
    logs = GenericRelation(ActivityLog)

class Product(models.Model):
    name = models.CharField(max_length=255)
    sku = models.CharField(max_length=50)
    logs = GenericRelation(ActivityLog)

class User(models.Model):
    email = models.EmailField()
    logs = GenericRelation(ActivityLog)

This is a legitimate use of GFK. Audit logs should be polymorphic. But rendering a page of 20 activity feed entries, each showing the target's name and a link, hits the database once per entry to resolve log.target: 20 individual single-row lookups.

If the audit trail also needs actor details, or the target's related data, the count multiplies fast. Twenty entries can easily become 60-80 queries before pagination.

The Solution

Three steps. First, batch-resolve every GFK lookup in the page at once using compound queries. Second, attach the results to each instance as a cached private attribute. Third, let serializers read the cache with a live-query fallback, so the optimization is optional and the code never breaks if you forget to run it.

Step 1: Resolve the targets in bulk, not one by one

Collect the log entries you want to display, then group their object_id values by content type. Fire one query per target model, map the results back by ID, and attach the resolved instances:

from collections import defaultdict
from django.contrib.contenttypes.models import ContentType

def hydrate_activity_targets(entries):
    """Resolve all ActivityLog.target references in bulk."""
    if not entries:
        return

    # Collect all (content_type_id, object_id) pairs from the page
    refs_by_ct = defaultdict(set)
    for entry in entries:
        if entry.content_type_id and entry.object_id:
            refs_by_ct[entry.content_type_id].add(entry.object_id)

    # Resolve content types dynamically from the entries. One query,
    # no hardcoded model list — inherited codebases gain new types
    # and this adapts automatically.
    ct_by_id = {
        ct.id: ct
        for ct in ContentType.objects.filter(id__in=refs_by_ct.keys())
    }

    # One query per target model, map results back by (ct_id, str(id))
    target_map = {}
    for ct_id, obj_ids in refs_by_ct.items():
        ct = ct_by_id.get(ct_id)
        if ct is None:
            continue
        model = ct.model_class()
        if model is None:
            continue
        for obj in model.objects.filter(id__in=obj_ids):
            target_map[(ct_id, str(obj.id))] = obj

    # Attach to each entry
    for entry in entries:
        key = (entry.content_type_id, str(entry.object_id))
        entry._resolved_target = target_map.get(key)

This resolves every target reference on the page, regardless of type, with one query per content type. For a feed mixing 4 types, that's 4 queries instead of 20. The ContentType map is built from the entries themselves (no hardcoded model list), so the function automatically handles content types added after the hydration code was written.

Step 2: Handle the related data with compound queries

Resolving the target object is only the first layer. Audit entries also need the actor's name, or a display string that lives on a related model. You can extend the hydration to fetch those in bulk too. The pattern is the same: bucket by content type, compound Q filter across all buckets, map back by (content_type_id, object_id):

from django.db.models import Q

def hydrate_activity_details(entries):
    """Bulk-fetch display details for all resolved targets on the page."""
    if not entries:
        return

    # Build a model → ct_id map up front. Unlike Step 1, display formatting
    # is inherently type-specific — a product shows name and SKU, a user
    # shows their full name — so hardcoding known types here is correct.
    ct_map = ContentType.objects.get_for_models(Product, User, Order)
    ct_id_by_model = {model: ct.id for model, ct in ct_map.items()}

    # Group entries by content type
    obj_ids_by_ct = defaultdict(list)
    entry_by_target_id = defaultdict(list)  # target.id → [entries with that target]
    for entry in entries:
        target = getattr(entry, "_resolved_target", None)
        if target is None:
            continue
        ct_id = ct_id_by_model.get(type(target))
        if ct_id is not None:
            obj_ids_by_ct[ct_id].append(target.id)
            entry_by_target_id[(ct_id, target.id)].append(entry)

    # Fetch products in one query
    product_ct = ct_id_by_model.get(Product)
    if product_ct in obj_ids_by_ct:
        product_display = {
            p.id: f"{p.name} ({p.sku})"
            for p in Product.objects.filter(
                id__in=obj_ids_by_ct[product_ct]
            )
        }
        for product_id, display in product_display.items():
            for entry in entry_by_target_id[(product_ct, product_id)]:
                entry._target_display = display

    # Fetch users with their profile in one query
    user_ct = ct_id_by_model.get(User)
    if user_ct in obj_ids_by_ct:
        user_display = {
            u.id: u.get_full_name()
            for u in User.objects.filter(
                id__in=obj_ids_by_ct[user_ct]
            ).select_related("profile")
        }
        for user_id, display in user_display.items():
            for entry in entry_by_target_id[(user_ct, user_id)]:
                entry._target_display = display

    # Repeat the same pattern for Order or any other content type.
    # Targets that don't match a handled type fall back gracefully through
    # the serializer's str(target) path.

Building the display map in a dict comprehension first keeps each pass over entries to O(n). One iteration per content type, not a nested loop over every object × entry combination. For 200 entries and 50 products, that's 50 + 200 checks instead of 50 × 200.

Step 3: Serializers that read the cache with a fallback

Serializers read the cached attributes when they're present, and fall back to a live query when they aren't, so the serializer works whether or not the hydration ran:

class ActivityLogSerializer(serializers.Serializer):
    target_name = serializers.SerializerMethodField()
    target_type = serializers.SerializerMethodField()

    def get_target_name(self, entry):
        display = getattr(entry, "_target_display", None)
        if display is not None:
            return display
        # Cache wasn't populated — fall back to a live GFK lookup.
        target = entry.target
        return str(target) if target else None

    def get_target_type(self, entry):
        target = getattr(entry, "_resolved_target", entry.target)
        if target is None:
            return None
        return type(target).__name__

The getattr(entry, "_target_display", None) pattern is the decoupling mechanism. If hydration ran, the attribute is present and entry.target never fires. If it didn't run, the serializer falls back to a live GFK query and everything still works. The hydration logic is an optional optimization — the serializer doesn't care whether it was called.

Why This Works

One query per content type, not per row. The id__in filter resolves all targets of a given type in a single query regardless of how many entries reference that type. A feed with 20 entries across 4 types goes from 20+ queries to 4.

The private-attribute convention is lazy and safe. _resolved_target and _target_display are set when hydration runs and silently absent when it doesn't. The getattr(..., fallback) pattern means no code path breaks. The serializer degrades to live queries without any conditional branching.

No schema change required. This pattern doesn't touch the models, doesn't need a migration, and doesn't alter how GFK works. It's a presentation-layer optimization. You can introduce it incrementally to the slowest pages and leave the rest untouched.

It composes with existing select_related/prefetch_related. If your queryset already uses ORM-level prefetch for non-GFK relationships (like select_related("actor")), the hydration runs after that, filling in only the gaps the ORM can't reach.

Design Decision: The Fallback Is Silent, and That's Both a Feature and a Risk

Because getattr(entry, "_resolved_target", entry.target) swallows a missing attribute silently, a typo in the attribute name (_resolvedTarget) will never raise an error. It'll just quietly bypass the cache and fire a live query on every call. The page still renders correctly, but your query count silently regresses.

Mitigations: keep the _ prefix convention consistent, test the query count in integration tests (not just correctness), and consider a debug-mode assertion that logs a warning when hydration is expected but the cache attribute is absent.

One more operational note: if the set of target types is large, the id__in per-content-type approach fires many small queries rather than one big one. At dozens of content types, a single query that fetches all targets of any type via UNION may be faster — but for the typical audit log with half a dozen entity types, the per-type approach is simpler and easier to debug.

The Result

An activity feed that used to cost ~60 queries for 20 entries — the initial queryset (1), a per-entry GFK target lookup (20), an actor display-name lookup per entry (20), and a related-field fetch per target (20+, e.g. user profiles, product details) — now costs about 6: one per target content type plus the initial fetch.

The two hydration functions compose between the queryset and the serializer:

entries = ActivityLog.objects.select_related("actor").order_by("-created_at")[:20]
hydrate_activity_targets(entries)
hydrate_activity_details(entries)
return ActivityLogSerializer(entries, many=True).data

No schema change, no migration, no ORM tricks. The hydration functions are drop-ins that run between the queryset and the serializer, and if you forget to call them, nothing breaks. The serializers fall back to live queries.

How are you handling N+1 across GenericForeignKeys in your apps? Are you hand-rolling prefetches, or have you found a different pattern? Drop your approach in the comments.

¡Hasta luego!

The Problem

Django is a request/response framework. It processes a request, returns a response, and moves on. Real-time notifications — a dashboard ticking up, an order status flipping live — need a server that holds a connection open for every connected client. That is a fundamentally different job.

The standard answer in the Django ecosystem is Channels. It moves you to ASGI, gives you consumers, and works well, especially when your real-time needs are deep and bidirectional.

Ours weren't. We needed server→client push: notify a user when an order completed, or when a payment landed. The connections were mostly idle. Channels gave us that, but it came with costs that started hurting at scale.

The concrete problem was this: every open WebSocket connection consumed memory and a small slice of CPU time on our app servers. A thousand connected dashboards was fine. Ten thousand, across dozens of tenants, each holding a persistent socket. Suddenly, our workers were doing two very different jobs at once. Serving fast API responses and babysitting long-lived, mostly-quiet connections. Both suffered.

What made it brittle was the reconnect storm. Deploy a new build, restart a server, or hit a brief network partition, and every connected client disconnects and immediately reconnects. All at once. That thundering herd of TLS handshakes, authentication, and subscription requests would spike CPU to 100% on every app server as it tried to spin up thousands of ASGI consumer instances simultaneously, occasionally knocking them over entirely before the retry backoff kicked in.

There's also the smaller but telling friction of auth. Authenticating the WebSocket handshake means reaching your existing auth (DRF/JWT) from inside an ASGI scope. I ended up writing middleware that reconstructed a DRF Request out of the raw scope just to reuse the auth I already had. It worked, but it was a sign: I was bending the framework to do something it wasn't built for.

The turning point was asking: why is my web framework in the business of holding connections at all?

For a fire-and-forget server→client push, it shouldn't be. There are servers built specifically to hold millions of open connections and do nothing else. The only two things your backend needs to do are say who's allowed to listen, and publish events.

The Solution

Put a dedicated pub/sub gateway in front of your app. I used Centrifugo, a standalone real-time server. Clients connect to it, not to Django. Django goes back to being a plain, boring WSGI/sync app and plays two small roles:

1. Issue a short-lived connection token that embeds which channels this user may subscribe to.

2. Publish events to the gateway over its HTTP API.

The gateway holds the connections. Django holds nothing.

Step 1: Issue a token that carries its own permissions

When a client wants to connect, it asks your backend (over a normal authenticated request) for a connection token. The token is a JWT whose claims list the exact channels the user may subscribe to. The gateway verifies the signature and authorizes subscriptions without a single database lookup:

# realtime/auth.py
import time
import jwt
from django.conf import settings


class RealtimeTokenService:
    """Issues short-lived JWTs for connecting to the realtime gateway."""

    def generate_connection_token(self, user) -> str:
        tenant_id = user.tenant_id

        # Channel grants are baked into the token, so the gateway authorizes
        # subscriptions with zero database lookups on connect.
        channels = [
            f"user_{user.id}",
            f"critical:user_{user.id}",
            f"tenant_{tenant_id}",
            f"critical:tenant_{tenant_id}",
        ]

        claims = {
            "sub": str(user.id),
            "exp": int(time.time()) + settings.REALTIME_TOKEN_TTL_SECONDS,
            "info": {"name": user.get_full_name(), "email": user.email},
            "channels": channels,
        }
        return jwt.encode(claims, settings.REALTIME_HMAC_SECRET, algorithm="HS256")

This is the key idea: token-as-permission. The channel names encode your authorization model. A user gets their own user_{id} channel and their tenant's tenant_{id} channel, and nothing else. Multi-tenant isolation falls out of the channel naming: a user simply has no grant for another tenant's channel, so the gateway will refuse the subscription.

Step 2: Hand the token out behind your normal auth

The endpoint that mints the token is an ordinary authenticated view. Your existing auth stack protects it; no ASGI gymnastics:

# realtime/views.py
class RealtimeTokenView(APIView):
    permission_classes = [IsAuthenticated]

    def post(self, request):
        token = RealtimeTokenService().generate_connection_token(request.user)
        return Response(
            {"token": token, "socket_url": settings.REALTIME_SOCKET_URL}
        )

The client takes {token, socket_url}, opens a WebSocket to the gateway, and subscribes to its channels. Django is now out of the connection entirely.

Step 3: Publish events over HTTP

To push an update, your backend POSTs to the gateway's publish API. No connection state, no sockets: just an HTTP call:

# realtime/publisher.py
import requests
from django.conf import settings


def push_event(channel, event_type, payload, *, recoverable=False, timeout=10.0):
    # The "critical:" namespace is configured on the gateway with message
    # history + recovery, so clients can catch up after a reconnect.
    final_channel = f"critical:{channel}" if recoverable else channel

    resp = requests.post(
        f"{settings.REALTIME_API_URL}/publish",
        json={
            "channel": final_channel,
            "data": {"type": event_type, "payload": payload},
        },
        headers={"X-API-Key": settings.REALTIME_API_KEY},
        timeout=timeout,
    )
    resp.raise_for_status()

Notice the critical: channel prefix. On the gateway, that namespace is configured to keep a short history so a client that briefly drops can recover missed messages on reconnect:

{
  "namespaces": [
    { "name": "critical", "history_size": 50, "history_ttl": "120s", "force_recovery": true }
  ]
}

Ephemeral events (a "user is typing" blip) publish to the bare channel; events you can't afford to lose (a completed order) publish to critical: and survive a reconnect.

Step 4: Make publishing reliable, and don't block the request

Publishing is a network call to a separate service. You do not want it on the request's critical path, and you want it to survive a transient blip. Wrap it in a Celery task with retries and backoff:

# realtime/tasks.py
import logging
from requests.exceptions import RequestException, HTTPError
from celery import shared_task
from .publisher import push_event

logger = logging.getLogger(__name__)


@shared_task(bind=True, max_retries=3, default_retry_delay=5, retry_backoff=True)
def publish_realtime_event(self, channel, event_type, payload, recoverable=False):
    try:
        push_event(channel, event_type, payload, recoverable=recoverable)
    except HTTPError as exc:
        # A 4xx error (bad API key, malformed payload) is a deterministic
        # failure that retries can't fix. Log it and drop it.
        # A 5xx error might be transient, so retry it.
        if 400 <= exc.response.status_code < 500:
            logger.error("Deterministic 4xx error on %s, dropping.", channel)
            return
        raise self.retry(exc=exc)
    except RequestException as exc:
        # Pure network timeouts or connection errors — retry with backoff.
        raise self.retry(exc=exc)
    except Exception:
        # A serialization bug won't fix itself on a retry. Log and drop it,
        # rather than burning three attempts on a guaranteed failure.
        # By not re-raising, Celery marks the task as successful and removes
        # it from the queue — no poison pill looping forever.
        logger.exception("Dropping unrecoverable realtime event on %s", channel)

That except split matters: retry the transient, drop the deterministic. A flaky network deserves another try; a payload that can't be JSON-encoded will fail identically three times in a row, so retrying it is just noise.

Firing an event from anywhere in your app is now a one-liner:

publish_realtime_event.delay(
    channel=f"tenant_{order.tenant_id}",
    event_type="order.completed",
    payload={"order_id": order.id, "total": str(order.total)},
    recoverable=True,
)

Why This Works

Your web tier goes back to being stateless. Django stays on WSGI. No ASGI migration, no async server, no sockets held in your workers. You can scale, restart, and deploy the web tier like any other stateless service. The open connections live on the gateway and aren't disturbed.

Connections scale independently. Holding a lot of idle connections is a specialized job. A purpose-built gateway does it on its own box, tuned for that, while your app servers stay sized for request throughput.

Auth has zero connect-time cost. Because the token carries its channel grants, the gateway never calls back into your database to authorize a subscription. Ten thousand clients reconnecting after a blip is ten thousand signature checks, not ten thousand DB queries.

Multi-tenancy is just naming. Tenant isolation isn't a separate access-control layer. It's the channel names in the token. There's no code path by which a user can subscribe to a channel they weren't granted.

Delivery is fire-and-forget but durable. Publishing happens off the request path via Celery, retries on transient failure, and the critical: namespace lets clients recover what they missed across a reconnect.

Design Decision: The Token Is a Cache, So It Can Go Stale

Baking permissions into the token is what buys you DB-free connects. But a token is a snapshot. If a user's access changes (you remove them from a tenant, say) and their token still has 24 hours to live, the gateway will keep honoring the old grants until it expires. You've traded revocation freshness for connect-time performance.

That's usually the right trade for a notification stream, but be deliberate about it:

• Keep the TTL short and have the client transparently re-fetch a token. Shorter tokens = smaller stale window.

• For true revocation, the gateway can be told to force-disconnect a user or refuse channels server-side. Reach for that only when a stream is sensitive enough to need it.

One more operational gotcha: a single gateway is tempting to share across environments, but tenant_42 in staging and tenant_42 in production are the same channel name: cross-talk waiting to happen. If you must share one broker, prefix channels with the environment (prod_tenant_42, staging_tenant_42) so the namespaces can't collide.

And to be honest about the path here: I shipped the Channels version first. It worked. But the friction of running an async server and bridging my existing auth into the ASGI scope is exactly what made the gateway approach worth it. If your real-time needs are deep and bidirectional (collaborative editing, presence), in-process Channels may genuinely fit better. For "push updates to subscribed clients," letting something else hold the sockets is the simpler system.

The Result

Adding a live update anywhere in the app is now one .delay() call. The web tier never learned what a WebSocket is. Connections, fan-out, history, and recovery are the gateway's problem; authorization is a signed list of channel names; delivery is a retrying background task. Django went back to doing the thing it's good at. And the real-time problem moved to a server built for it.

How are you doing real-time in your Django apps — in-process with Channels, or have you pushed connections out to a gateway? I'd love to hear what's worked for you in the comments.

¡Hasta luego!

The Problem

In our app, a product's name or price can change from eight different places. The edit page. Bulk import. The variant editor. A pricing rule engine. An API endpoint that processes webhooks from suppliers. Every few weeks, someone adds a new feature and creates yet another code path that mutates a product.

We needed every one of those changes, no matter where they came from, to sync to an external marketplace. The naive approach would be to add a sync call to each code path. That's eight places to maintain (and counting), eight chances to forget, and eight places that break if the sync API changes.

Django's post_save signals solve the discovery problem: hook into a model's save event and you catch every change, from every code path, in one place. Signals get a bad rap — fairly, they make control flow hard to trace. But when you need to react to changes from everywhere without touching anywhere, this specific discovery problem is exactly what they were designed for.

There's a catch, though. If ten prices change in a single request, say, a bulk import, a naive signal handler fires ten times. That's ten API calls in rapid succession. At best, you are wasting resources. At worst, the external API rate-limits you.

We needed signals to detect changes, but we needed to batch them.

The Solution

Here's the three-part pattern:

1. A signal handler that collects change references instead of acting on them immediately.

2. A per-thread set that deduplicates for free — adding the same product twice does nothing.

3. A flush callback deferred to transaction.on_commit that processes everything once the database transaction lands.

Step 1: Register the signal

In your app's apps.py, connect post_save to the model that holds pricing:

# shopping/apps.py
from django.apps import AppConfig

class ShoppingAppConfig(AppConfig):
    name = "shopping"

    def ready(self):
        from django.db.models.signals import post_save
        from shopping.models import PriceRecord
        from shopping.signals import on_price_change

        post_save.connect(
            on_price_change,
            sender=PriceRecord,
            dispatch_uid="shopping_price_change",
        )

dispatch_uid prevents duplicate connections if ready() runs twice, a common gotcha during development with auto-reload.

Step 2: Collect, don't act

The signal handler doesn't call an API. It just adds a reference to a set and registers a flush callback:

# shopping/signals.py
import threading
from django.db import transaction

_local = threading.local()


def _get_pending():
    if not hasattr(_local, "pending"):
        _local.pending = set()
    return _local.pending


def on_price_change(sender, instance, **kwargs):
    # Record just enough to look up the product later
    _get_pending().add(instance.object_id)
    transaction.on_commit(flush_changes)

That's it. Four lines of logic. The handler doesn't care how many prices changed or where the change came from. It just records what changed and defers action to the flush.

Notice that we use threading.local() instead of a standard module-level variable. This ensures that each thread gets its own isolated storage.

Why transaction.on_commit? If the transaction rolls back, the price change never happened, so the flush callback is discarded. You never sync data that wasn't committed.

Step 3: Flush once per transaction

When the transaction lands, the flush handler fires. It snapshots the set, clears it immediately, and processes everything in one batch:

def flush_changes():
    pending = _get_pending()
    refs = pending.copy()
    pending.clear()

    if not refs:
        return

    from shopping.services import SyncService
    SyncService.handle_price_changes(refs)

The key detail: we copy the set before clearing it. If clearing happened after processing, and processing raised an exception, stale refs would linger into future transactions. Snapshot-first is defensive.

This clear() is also what keeps requests perfectly isolated. Once a transaction commits and the flush runs, the set is empty and ready for the next request.

Step 4: Resolve and dispatch

The service layer resolves the raw references into business entities, groups them by destination, and dispatches one task per group. The grouping is the important part. One API call per store, regardless of how many products changed:

# shopping/services.py
from collections import defaultdict

class SyncService:

    @classmethod
    def _resolve_to_products(cls, refs: set[int]):
        """
        Resolve product ID references to actual Product instances
        with their Store relationship.  Fetches everything in ONE
        query using filter(id__in=...), silently ignoring stale
        IDs that no longer exist.
        """
        products = Product.objects.filter(
            id__in=refs
        ).select_related("store")

        resolved = []
        for product in products:
            resolved.append((product, product.store_id))
        return resolved

    @classmethod
    def handle_price_changes(cls, refs: set[int]):
        resolved = cls._resolve_to_products(refs)

        # Group changes by the store they belong to
        by_store = defaultdict(list)
        for product, store_id in resolved:
            by_store[store_id].append(product)

        # One API call per store, regardless of how many products changed
        for store_id, products in by_store.items():
            sync_to_marketplace.delay(store_id=store_id, products=products)

The sync_to_marketplace task is a Celery task that calls the external API. It's configured with retries and backoff for transient failures:

@shared_task(bind=True, max_retries=3, default_retry_delay=60)
def sync_to_marketplace(self, store_id, products):
    try:
        provider.bulk_update(store_id, products)
    except Exception as exc:
        raise self.retry(exc=exc)

Why This Works

Deduplication is free. A set naturally deduplicates, adding the same object_id twice is a no-op. If a price changes twice in the same request (say, a pricing rule recalculates it), the flush handler sees it once. And when it fires, it reads the latest price from the database. The most recent value always wins.

Transaction safety is built-in. transaction.on_commit guarantees the flush only runs after the database confirms the change. If the transaction rolls back (a validation error, a constraint violation, a raise somewhere), the callback is discarded. You never sync phantom data.

Batch resolution avoids N+1. The service resolves all references in bulk queries, not one at a time. For 50 changed products, it takes exactly 1 query regardless of count. No per-product lazy loading.

Design Decision: Avoiding the Global State Pitfall

You might be wondering why we used threading.local() in Step 2 instead of a simple module-level variable like _pending_changes = set().

A basic module-level set shares state across every request handled by the same worker process. If User A's request rolls back, stale refs from their failed transaction sit in the global set. When User B's request commits ten minutes later on the same worker, the flush accidentally picks up both User A's and User B's products.

By using threading.local(), we protect against this cross-request leakage. Even if a transaction rolls back, any leftover references in that thread's set will simply be cleared on its next successful commit. And in the rare event a stale reference makes it to the resolver, it evaluates to nothing and is skipped silently.

One thing to watch for: use .filter() when looking up products in your resolver, not .get(). .filter() returns an empty queryset gracefully. .get() throws DoesNotExist and tanks your flush.

The Result

The user experience is deceptively simple. A user toggles "Sync product prices" on a store configuration page. From that moment on, any price change from any code path in the application syncs to the external marketplace within seconds.

No one has to remember to add a sync call to new features. No one has to track down every place a price can change. No one monitors a queue for failures (Celery retries handle that). The system just works.

How are you handling external API syncs in your Django apps? Are you using signals, or do you prefer a different pattern? Drop your approach in the comments.

¡Hasta luego!

Before moving on with this tutorial, there is a prerequisite which is detailed in this guide. You can call it pre-deployment. Please go through it and come back once it's checked ☑️

Also, you need to create an account on Heroku(obviously).

Now, let's begin

Procfile

This tells heroku how to use our app.

touch Procfile

The configuration varies by the app but this should do. Add the configuration below to your Procfile

release: python manage.py makemigrations bookgrid_app
release: python manage.py migrate

web: gunicorn bookgrid_proj.wsgi

Where ‘bookgrid_proj’ is the name of your django project and ‘bookgrid_app’ is the name of your Django app.

Runtime File

This tells Heroku what version of Python to use for our app

touch runtime.txt

Open the file and paste the python version below. Or anyone most compatible with your app and heroku from this list

python-3.8.12

Django-Heroku

This is a Django library for Heroku applications that ensures a seamless deployment and development experience. It is very much needed if you are deploying your app on Heroku

To install the package run

pip install django-heroku

In your settings.py file, at the very bottom add

import django_heroku
django_heroku.settings(locals())

Heroku Deployment

You need to have an account with heroku. If you don't, create one here.

Login via the command line or terminal with

heroku login

Then create a new heroku app, where acel-app is the name you wish to give your app

heroku create acel-app

Now configure git so that when you push to Heroku, it goes to your new app name

heroku git:remote -a acel-app

Then create a PostgresSQL database on heroku for our app

heroku addons:create heroku-postgresql:hobby-dev

And manually add our environment variables except DEBUG and DATABASE_URL

heroku config:set SECRET_KEY='(-e%3z3yp5qsirfl6_+9=ko#!r6%0am8=^x9a))p2)3y-24g%*'

If we had other things in our .env file like email host or cloud storage configuration for images and videos, we’d have to manually add it to heroku as well

Using email host user and email host password in the screenshot above as an example

heroku config:set EMAIL_HOST_USER='mattew@gmail.com'
heroku config:set EMAIL_HOST_PASSWORD='yyuiuilo7tuy'

Now it’s time to push our code up to Heroku itself and start a web process so our Heroku dyno is running.

git push heroku main

heroku ps:scale web=1

The URL of your new app will be in the command line output or you can run heroku open to find it.

Now we need to migrate our PostgresSQL database and create a superuser

heroku run python manage.py makemigrations bookgrid_app

heroku run python manage.py migrate

heroku run python manage.py createsuperuser

AND WE ARE DONE AMIGOS!

Thanks for following to the end and I hope it was helpful.

¡Hasta luego!

Before moving on with this tutorial, there is a prerequisite which is detailed in this guide. You can call it pre-deployment. Please go through it and come back once it's checked ☑️

Also, you need to create an account on Railway(obviously).

Now, let's begin.

Installing Nixpacks

Run the command below in your terminal if you use Ubuntu or WSL2. Else you can check for other methods here.

curl -LO https://github.com/railwayapp/nixpacks/releases/download/v2.0.11/nixpacks-v2.0.11-amd64.deb sudo dpkg -i nixpacks-v2.0.11-amd64.deb

Installing Railway CLI

You can install this using the shell script below if you're on macOS, Linux or Windows via WSL. Just run the command in your applicable terminal. You can check for other methods here.

bash <(curl -fsSL cli.new)

Login

railway login

Create a Project

A project is like a Github Organization or an Heroku Pipeline that defaults to the production environment. You can also create other environments for staging, testing, etc

railway init

Associate Directory to Project

Basically, this links the current directory (folder) you're in, to your Railway project. Very useful, especially as you can have multiple projects.

railway link

Navigate with the arrow keys and hit enter to select a project.

Environment Variables

Railway may have asked you to let them set up your environment variables from your .env file while you were deploying with railway up. That works but you may want to modify or add more. To see all existing environment variables, run

railway variables

To set or modify a variable

railway variables set {VARIABLE_NAME}:{VARIABLE_VALUE}

Procfile

Procfiles are a popular format used to specify a web/release process. To use this you need to create a Procfile in your root directory.

touch Procfile

Then paste this into it

web: gunicorn {YOUR_DJANGO_PROJECT_NAME}.wsgi

release: python manage.py migrate

Deploy

At this point, our app should be ready for a smooth deployment. You can do this with

railway up

It then builds and deploys your app on Railway 🎉

Nixpacks

If you had a successful deployment, you can skip this. However, if you have a psycop2g dependency, you'll run into an error while trying to deploy (as at the time of writing this). The fix for this is to install a postgresql nix package. First, create a file called nixpacks.toml in your root directory touch nixpacks.toml Then paste this snippet into it [phases.setup] nixPkgs = ["...", "postgresql"]

Port

After deploying your app, you need to set up a port number as Railway doesn't do this for us out of the box. Login to Railway on your web browser. Navigate to your project, then to your web deployment, then to your settings, and then set your port to 8000 as is the default for Django. Or whatever you want to use.

Shell commands

There are where we would need to run some commands directly in the hosted environment. With Railway, we can do this in a subshell that makes use of our hosted app's variables.

railway shell

This opens up that subshell. And for example, we can then create a superuser as we usually do with

python manage.py createsuperuser

Domain name

After our app is deployed, we need to generate a domain name for it so that it becomes accessible as Railway does not generate one by default. Pretty much the same process for setting up our port earlier.

End

And that's all that needs to be done! Thanks for following through to the end, and let me know if you encountered any issue not mentioned here.

¡Hasta luego!

January

Built my portfolio site

Applied for a couple of jobs

February

Applied for a couple of jobs

I was losing interest in Frontend Development cause it didn't seem to be leading anywhere for me. Also, I'd later find out I prefer to write C than write JavaScript

So I decided to dabble into Data Science

March

Applied for and got into Data Science Nigeria’s AI Wednesday program to learn machine learning

Completed and got the certificate for it in April

After completing the AI Wednesday program, I learnt Data Science was a field I didn't want to go into.

At this point, Zuri was open for internship applications so I used it as an opportunity to try out another field

April

I delved into backend development this time, with Django.

Zuri began fully this month. My track started with Python (which was basically a refresher for me) before moving to Django

May

Learning Django at Zuri

First semester exams in school (I think)

June

At Zuri, we had completed the learning phase and now in the project phase

I was the team lead for my team.

Leading the team was quite tasking cause though I had some experience leading a team (this was not my first internship), it is a different ball game when you have beginner level knowledge of your stack.

I had not even done a “Hello World” with Django Rest Framework before then, but we were able to get some work done. Luckily, there was someone more experienced with the stack on our team who helped out a lot

July

Finished the project phase of the internship at Zuri

Couldn't complete the project. And though we had several endpoints ready from the backend team, when the only thing to show for it is a working Sign up, Log in and Homepage, the endpoints don't matter. Especially when you're the overall team lead

Also, dey change am for designers once in a while.

August

Was focusing on school after the four-month internship

Started learning cloud computing with GCP on Pluralsight

September

Second semester exams

Aced the first phase exam of the cloud computing program on course(s) I was taking

Learned a lot about the cloud and how GCP works

I was actually learning with someone else's account who got access to it through a GADS scholarship

Considering; how time consuming the course was, the certificate wouldn't be in my name(in a field that more certificate-first), I decided to discontinue learning. Thankful for the opportunity to have learnt what I did

October

Took a Coursera course on Django offered by the University of Michigan through AUTC

Applied (volunteered) for Tutor roles at ECX and GDSC UNILAG. Got both

Continued learning cloud computing, but this time through MTC-UNILAG on Microsoft Azure

November

Started teaching Django at GDSC

Attended the UnStack Conference

Attended DevFest Lagos

Met friends I had made online

Made new ones too

December

Still tutoring the Django track

Still learning cloud computing with Azure

Finally got a mentor 🥺, He doesn't know it yet. Lemme say Pseudo-mentor for now

The Good

• Ticked off 4/7 things on my todo list for 2021
• Connected with people a lot more this year. Both online and offline
• Developed some level of proficiency in a skill I feel at home with
• Got a mentor
• Didn't lose any friend, nor did any friend lose a loved one

The Bad

• Hopped around a lot from one tech stack to the other
• Didn't get a paid gig or job this year
• Was too comfortable doing things on my own without getting guidance from others. Led to a lot of time wastage. Not having a mentor didn't help either

Goals for 2022

• Get a paid job/gig. Then do like 15x before the year runs out
• Get better grades in school
• Purchase a Real Madrid jersey from the official store
• Network more. Build on top of existing relationships

Takeaways

• Get a mentor. Or at least have people you can ask for help and advice
• Pick a skill and learn it well. Don't be tech rabbit
• Network. Make friends. Except you're exceptionally brilliant, being introverted won't do you much good
• Write articles. I'm not an article person myself but writing articles about bugs you fix, or how you added a feature etc will help you later on. You don't wanna open multiple stackoverflow tabs to everytime to do something you've done before. Trust me on that

Thanks for reading and I wish you an outstanding 2022 🎊

• creating your mailjet account
• creating the SMTP server on mailjet
• installing the django-mailjet package
• connecting it to your django app

Though this article is gonna be focusing on Django as the backend, the same process should apply to whatever backend framework you wish to use. You'll just have to check if there's a package for mailjet that works with your framework

NB: You'll need to have knowledge of Django or whatever backend framework you use. We are simply replacing the default SMTP server provided in django with a better option. And yes, it's free! 😙

Creating your Mailjet Account

Click on this link and let's get started. That should lead you to the page below. Enter your email address and password, then click on sign up.

That takes up to the page below. If you are currently unemployed or a student, you can fill in Organization name with your name, Organization URL with a link to your portfolio or blog. Then select Other under Main industry

You don't need to add a payment method. Click on Complete order

You should get an email from mailjet to activate your account

Creating the SMTP server on mailjet

After activating it, you'll be led to this page. Click on getting started as a developer

What we need is a SMTP server so click on SMTP relay and continue

And here it is folks. We have our SMTP server set up and begging to be used!

Installing the django-mailjet package

If we just use the keys provided by Mailjet in our app, we'll run into errors. And that's where django-mailjet comes to the rescue. This package helps us configure our email backend to work seamlessly with Mailjet.

Install the package using

pip install django-mailjet

Connecting it to your django app

Now, the final step. In your settings.py file, add the following settings.

EMAIL_BACKEND = 'django_mailjet.backends.MailjetBackend'
EMAIL_HOST = 'in-v3.mailjet.com'
MAILJET_API_KEY = "your mailjet api key here"
MAILJET_API_SECRET = "your mailjet secret key here"
EMAIL_PORT = 587
EMAIL_USE_TLS = True
EMAIL_USE_SSL = False
EMAIL_TIMEOUT = 30
DEFAULT_FROM_EMAIL = 'sender_name <email_name>'

Where sender_name is a custom sender name and email_name is an email address you want the emails to be sent from. Note that email_name must be registered on your mailjet account.

And we're done! Don't forget to store your API_KEY and API_SECRET with environment variables

Thanks for reading to the end. A like would be appreciated 😊

¡Hasta luego!

Below is a list of steps to successfully set up your django project for deployment:

1. Environment Variables

2. Gitignore

3. Debug and allowed hosts

4. Secrect key

5. Static files

6. Gunicorn

7. Requirements file

8. Git & Github

First things first, we'll need to open our text editor and terminal. Now navigate to your project folder and activate your virtual environment. Let's begin!

NB: All single line code snippets are to be executed in your command line

Environment Variables

Before pushing our code to github, we don't want every single thing in our project leaving our PC. An example of such is the secret key for our app. To curb this we'll make use of a .env file to store all of our application's vital info.

pip install environs~=8.0.0

touch .env

Then in the settings.py file add

from environs import Env # new
env = Env() # new
env.read_env

Gitignore

We do not want git to track all our files like .env and our local database. To take care of that we make use of a .gitignore file.

touch .gitignore

Open .gitignore in your text editor and add the following files

.env
__pycache__/
db.sqlite3
.DS_Store # Mac only

Debug and Allowed hosts

It is vital that we set debug to false when moving to production and limit allowed hosts to prevent unauthorized access to our application.

In the settings.py file, update

DEBUG = env.bool(“DEBUG”, default=false)
ALLOWED_HOSTS = [‘.herokuapp.com’, ‘localhost’, ‘127.0.0.1’]

In the .env file add

export DEBUG=True

Secret Key

This is a very important info we don't want leaving our PC. Hence, we'll add it to our .env file

In the settings.py file you should see something like this

SECRET_KEY  =  '(-e%3z3yp5qsirfl6_+9=ko#!r6%0am8=^x9a))p2)3y-24g%*'

In the .env file add

export SECRET_KEY=(-e%3z3yp5qsirfl6_+9=ko#!r6%0am8=^x9a))p2)3y-24g%*

Notice that there's no quotation mark and space when adding it to the .env file. Also, each secret key is unique to a django project so don't expect this secret key to match with yours.

Now in the settings.py file, update

SECRET_KEY = env.str(“SECRET_KEY”)

Databases

We need to configure our database because while the default(sqlite3) is okay for local development, it's not sufficient for production. When deploying to Heroku, our app is automatically assigned a free PostgresSQL database. So we just need to configure our app to use sqlite3 locally.

In your settings.py file, update

DATABASES = {
"default": env.dj_db_url("DATABASE_URL")
}

Add this to the .env file

export DATABASE_URL=sqlite:///db.sqlite3

Then install the dj-database-url to utilize the DATABASE_URL environment variable to configure your Django application

pip install dj-database-url

Then we need to install Psycopg, a database adapter that lets our Python app talk to the PostgreSQL database.

pip install psycopg2-binary~=2.8.5

Static files

You can skip this if you're deploying a DRF app as it doesn't include any static file. If you're using django on the other hand, we have something extra to configure. We are doing this because django doesn't support serving static files in production itself

pip install whitenoise~=5.1.0

Then we need to add the configurations for whitenoise in our settings.py file

INSTALLED_APPS = [
...
'whitenoise.runserver_nostatic',         # new
'django.contrib.staticfiles',
]
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'whitenoise.middleware.WhiteNoiseMiddleware',             # new
...
]
STATIC_URL = '/static/'
STATICFILES_DIRS = [str(BASE_DIR.joinpath('static'))]         # new
STATIC_ROOT = str(BASE_DIR.joinpath('staticfiles'))            # new
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'     # new

Then make directories for our static files

#Run each line one by one in your command line/terminal
mkdir static
mkdir static/css
mkdir static/js
mkdir static/images

Then run the collectstatic command for the first time to compile all the static file directories and files into one self-contained unit suitable for deployment.

python manage.py collectstatic

As a final step, in order for our templates to display any static files, they must be loaded in. So add {% load static %} to the top of the base.html file.

{% load static %}
<html>
…

Gunicorn

We need to install gunicorn as the production web server

pip install gunicorn~=19.9.0

Requirements File

This lets heroku know what dependencies are needed for our app so it can be installed. First run pip freeze > requirments.txt to create a requirements.txt file that contains all our app's dependencies.

Git & Github

I'm assuming you're conversant with git and github by now. Just commit your latest changes and push it to your online repo on Github or Gitlab. If you don't know how to do that you can check out this article.

Deploy on Specific Platforms

At this point, we have covered most of the steps you'll need to deploy your app. Whatever is left is platform-specific, and I have covered a few of them. Please click on one of the links below to continue your deployment on any platform of your choice.

• Deploy on Railway

• Deploy on Heroku

Resumed for my 2nd year in Unilag. Finally moved in to a hostel with my dad’s permission after he wanted me to go from home till I finish…lmaooo. I moved in on my own (off and on) in my second semester. At times its good to be stubborn/rebellious, lool.

Then I started attending ECX’s weekly classes for frontend late January/early February. That’s where I began learning frontend development. Signed up on github, created my first repo and my first website (It looks like Beans mixed with Amala). Was stressful having to go to the venue right after classes but it was worth it.

Was preparing for tests before ASUU drank Alomo bitters and went on a two weeks strike. I was low key happy so that I’ll use the time to prepare properly for my tests and complete my assignments. Then Covid-19 came, sent us into panic mode and sent us packing. The whole thing made ASUU look unserious and they now decided to go on indefinite strike sighs

With the way Covid-19 was going, I kuku(immediately) knew we wouldn’t resume till next year, so I chose to improve my frontend skills. Luckily, ECX came up with a #30daysofcode coding marathon. I registered willing to complete the program.

I started well, finished not so–naa I didn’t finish. From day 1 to day 5 were seamless. Relatively easy tasks, but by the day each task increased in difficulty. I think I managed to get to day 8/9 and fell sick. Couldn’t code for days but I recovered did my best to catch up then broke down. I had gotten Ill twice in one month! The first thing to come to mind would have been Covid-19 but I also fell Ill multiple times while in school. I took my time to recover. At this point I was far behind and just hoped to complete the tasks up to day 15.

While on it, my laptop broke down. sighs I was convinced my village people were on my matter and decided not to stress myself anymore. Later a friend reached out and asked if I was still participating in the #30daysofcode. We talked and he gave me ginger to continue, I resumed. Remember, my laptop was still bad and there was a very strict lockdown (as a then). I had to become a self-taught hardware engineer. Watched one or two videos, took the risk and dismantled my laptop. Luckily, all I had to do was remove my RAM cards, CMOS battery and insert them back… It worked! I assembled it and it worked like it used to. Village people 3 – 1 Acel. At the end of it all I could only complete 14 tasks–needed 15 to at least get a certificate of participation.

Another #30daysofcode presented itself. I participated but approached it a bit differently. Registered for the Frontend Intermediate and Python beginner track. Along the way, day 6 or 7, I dropped the frontend track. Why?

• I was doing other things at home. I live with my parents so I don’t have full control over my time.
• I didn’t know jack about JavaScript so I had to learn it on the go. There just wasn’t time for that.
• Plus Frontend being time consuming for even the littlest of things, I had to drop it. No time and I couldn’t afford to fall sick again.

So, I continued with the Python track and completed it! Python wasn’t completely new to me as I had learnt a bit of it before. So, half of the cohort was revision and the other half learning best practices and other cool stuff in Python.

This was May and I had to decide between continuing with Frontend or moving to Data Science. I had gained some insight on data science from TECH SKILLS HUB headed by Arinze but data science, data engineering, data analysis, AI, ML etc. were all so vague that one could get lost in the learning process. So, I opted for Frontend development that had a learning path one could follow.

I applied for hnginternship and started learning JavaScript on Udemy. I didn’t have any hiccups while learning JavaScript except for the data burnt. I also paid for a course I haven’t taken till now. A whole 14k in this terrible economy sighs. It’s not that I have money oo, but HNG happened.

Learning online and all is cool but when you’re done what you get is certificates. This was a chance to get experience in what I was learning. So, I took it and put what I was learning on hold. HNG internship was an experience that’s difficult to describe. Completing tasks before deadline, having to suddenly work with people you’ve never met on short notice yet compelled to deliver on time. Honestly the joy of completing tasks was immense but so was the task that followed. You could be having fun one minute, debugging codes the next. Playing games one second, preparing for your tasks the next. Relived by night, sent into panic mode by morning.

Yet, I wanted to finish it. Coming from someone that could easily fall sick if he overstresses himself, that’s how much I enjoyed it. I made friends, bantered, had Slack crushes. During this period, I was so immersed in the program that I became a Painite on WhatsApp. Quite difficult to find there. The tasks were difficult, very difficult to complete, but I kept pushing. Till I could push no more and that was stage 5. I broke down once again. That didn’t stop me though. The fact that everyone kept trying their best and wanted to get to the next stage was enough motivation for me.

I worked with an overworked body and days later my will failed me. I decided to stop but this time, it was my mum who reached out. I had gotten better but I was late to get a task–well almost. I got one quite late, did it and was able to make it to the 7th stage. My enthusiasm was back. I went on, learning a new technology for the next stage and applying it as much as I could. I didn’t make it past this stage, but I was happy I made it that far. Seven whole stages, stressful as f**k, and was quite time consuming. Also visited their office at Yaba once. I used my last days to have fun on the random channel and other fun channels. I learnt how to work in teams, lead teams, how to use GitHub better, how to use Slack , new tools and made my way to Tech Twitter. I thank HNG for the experience.

Later on, a friend of mine became motherless. Yeah. It wasn’t my mum, I know but I questioned a lot of things. I was quite sad that week, really sad. I asked my mum how it felt to lose someone close to you and she said it’s painful and the pain never leaves. You just accept it. I visited this guy and didn’t know what exactly to say. And incase you’re wondering, I did imagine losing a loved one. It’s not like I wanted to lose someone, but I just needed a good idea of what it felt like. Sad phase for me this year.

Participated in WeJapa’s Internship, August this year. There were hiccups and it was more or less you learning on your own. Just one task given which I completed. No vibes, just Insha’Allah. I don’t even know why I wasn’t given a certificate. Hopefully they do better next year.

Participated in ECX’s Internship that held in September. We were given a task each week during the internship. The first task was individual based and the rest, in groups. I lead my group during the internship. Compared to other groups you could say I had active members, but none of them were designers. It’s either they weren’t online or had an issue with light or something. But there was always a significant delay from their end hence, the backend devs were left with little or no time to complete the projects. This was a time I wished I knew a bit of backend so I could assist them. Unfortunately, NodeJS learning materials aren’t easy to find. We even had to outsource designs for one or two projects. My experience here taught me a lot about how to manage teams and people.

In October I took an in-depth bootstrap course on Coursera . This was when I really understood the struggle with online learning/ tutorials. My learning experience on Udemy and Coursera were quite different. On Coursera, there’s always an assignment(s) at the end of every week and you can’t slack a bit cause the modules are timed. Plus, you also have to mark other students’ assignment. Quite stressful but I finished it on time. Just so you know, I’m an advocate for pure CSS, no frame works. Unless for things like carousels, animations, etc. I learnt bootstrap so I can read people’s code better. Not everyone is like me and a lot of people use bootstrap. Not to mention that some companies make its usage compulsory. So, if I’m gonna work in teams, I might as well learn it properly.

Completed the JavaScript course I started earlier in the year and also learnt about Progressive Web Apps and how to convert web apps to PWAs.

I worked on my Portfolio and Resume. Was something I had been wanting to do but just kept postponing it cause I felt I didn’t know enough to get a job anyway. Eventually did it cause of the EnyataProjectBuildup. Designed (in my head) and built my portfolio. Worked on my Resume with Canva. Thanks Ugonna for the Resume review.

Was more active in church particularly at the start of December. Months away from church really made me question and reaffirm my faith, beliefs and doctrines as a Christian. Took me a while to get back to my best.

27th of December, I heard that a friend/primary schoolmate lost his dad a month ago. We live on the same street. What is should I say funny, is that we got to know through a banner announcing his death on our street. Sighs

29th of December, I heard that a friend/secondary school classmate lost his mum exactly a month ago. He told me himself in the DM.

Apparently, he posted the news of her death on his WhatsApp status. I also have class mates from Sec school I chat with yet I didn’t know, didn’t even get a clue about it. We chatted. After that, I began to wonder how detached I was from friends and family, what was I doing wrong, the possibility that big things(good/bad) had happened in the life of my friends and I have no idea about it. Am I too self-centered? Or introverted? Or me just having a very bad habit of not keeping in touch? I couldn’t pinpoint a reason but decided to try to be more active socially. Even if I’ll have to leave my comfort zone of staying at home, not checking out people’s WhatsApp status, initiate chats more, even if it’s just to say hello and be a lot more active in group chats. Especially those that include friends and family.

My finances really took a hit and so did my body. I don’t think I’ve ever fallen ill so many times in one year. My relationship with friends and family also took a hit. This year wasn’t my best, neither was it my worst.

What I want for 2021

• I want to be a better person next year
• I want to do really well in school next year
• I want to be a better programmer next year
• I want to get gigs/jobs next year
• I want to be a Microsoft Learn Student Ambassador next year
• I want to have a good social life online and offline next year
• I want have a far better health next year

And how could I forget, my phone was stolen on the 1st of January 2020 and my Ulcer resurfaced December this year. And yes #EndSars. I couldn’t leave my house but I’m happy to have participated as much as I could online.

I apologize for having to make you read so much, I didn’t think it would be this long.

Happy New Year!