Build a multitenant Django application

A multitenant application serves several customers (tenants) from one deployment while keeping their data apart. With django-tenants, each tenant gets its own PostgreSQL schema and its own subdomain, such as acme.shop.example.com, and a public schema holds what tenants share. On Sevalla, a wildcard custom domain sends every subdomain to the application, and a job migrates every schema before each deployment.

At a glance

This guide changes the application from Deploy a Django application:


Processes	The `Migrate` job stays as it is: django-tenants’ `migrate` migrates every schema
Services	The same PostgreSQL database, with one schema per tenant
Size	S1 or larger for the web process, because custom domains aren’t available on H1

Environment variables

Variable	Required	Available during	Secret	Value
`ALLOWED_HOSTS`	Yes	Runtime	No	The application’s domain and the wildcard domain with a leading dot: `storefront-x7k2m.sevalla.app,.shop.example.com`
`DB_URL`	Yes	Build and runtime	Yes	From the internal connection, as before. The settings no longer fall back to SQLite, so Ingot’s build needs it too

The deploy guide lists the other variables.

Before you begin

A Django project deployed on Sevalla with a PostgreSQL database, as in Deploy Django. Use a database that holds no data you need yet: django-tenants expects to manage every schema from its first migration.
A domain whose DNS you control, such as shop.example.com.
The web process on a size larger than H1: custom domains aren’t available on H1. See Scaling.

Install django-tenants

Install django-tenants and update requirements.txt:

pip install django-tenants
pip freeze > requirements.txt

django-tenants 4.0 supports Django 5.2, 6.0 and 6.1, on PostgreSQL only.

Add the tenant models

Create an app for the tenants and their domains, and an app with the tenants’ own features:

python manage.py startapp customers
python manage.py startapp shop

customers/models.py

from django.db import models
from django_tenants.models import DomainMixin, TenantMixin


class Client(TenantMixin):
    name = models.CharField(max_length=100)
    created_on = models.DateField(auto_now_add=True)

    # Create and migrate the tenant's schema when it's saved.
    auto_create_schema = True


class Domain(DomainMixin):
    pass

Configure the project

In storefront/settings.py, replace INSTALLED_APPS with the apps every tenant shares and the apps each tenant gets in its own schema, and name the tenant models:

storefront/settings.py

SHARED_APPS = [
    "django_tenants",  # must come first
    "customers",
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
]
TENANT_APPS = ["shop"]
INSTALLED_APPS = SHARED_APPS + [app for app in TENANT_APPS if app not in SHARED_APPS]

TENANT_MODEL = "customers.Client"
TENANT_DOMAIN_MODEL = "customers.Domain"

Put TenantMainMiddleware first in MIDDLEWARE:

storefront/settings.py

MIDDLEWARE = [
    "django_tenants.middleware.main.TenantMainMiddleware",
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    # ...the rest of the middleware...
]

Replace ROOT_URLCONF with the tenants’ URLs and the main site’s URLs on the public schema:

storefront/settings.py

ROOT_URLCONF = "storefront.urls"
PUBLIC_SCHEMA_URLCONF = "storefront.urls_public"

Replace DATABASES with django-tenants’ PostgreSQL backend and its router:

storefront/settings.py

DATABASES = {
    "default": env.db("DB_URL", engine="django_tenants.postgresql_backend"),
}
DATABASE_ROUTERS = ["django_tenants.routers.TenantSyncRouter"]

TenantMainMiddleware comes before Django’s own middleware: it picks the tenant, and so the schema, from the request’s host. If you added the health check middleware, keep it in front of TenantMainMiddleware, because the probes’ host matches no tenant.
django.contrib.auth and django.contrib.sessions are both shared here. Keep them together, in SHARED_APPS or in TENANT_APPS: a session points at a user, so both tables must be in the same schema.
DB_URL comes from the database’s internal connection, which makes it available during the build too. The settings no longer fall back to SQLite, so for local development, add a local PostgreSQL database to .env, for example:
.env
DB_URL=postgres://storefront:storefront@localhost:5432/storefront

If the application builds from your own Dockerfile, its build doesn’t get DB_URL, and collectstatic stops with ImproperlyConfigured: Set the DB_URL environment variable. Give it a placeholder next to the placeholder SECRET_KEY. collectstatic loads the settings but doesn’t connect to the database:

Dockerfile

RUN SECRET_KEY=collectstatic-placeholder \
    DB_URL=postgres://collectstatic@localhost/collectstatic \
    python manage.py collectstatic --noinput \
    && python -m compileall -q .

Add the views and URLs

shop/views.py

from django.http import HttpResponse


def index(request):
    return HttpResponse(f"Welcome to {request.tenant.name}")

storefront/urls.py

from django.urls import path

from shop import views

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

storefront/urls_public.py

from django.contrib import admin
from django.http import HttpResponse
from django.urls import path

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", lambda request: HttpResponse("Shop platform")),
]

Create the migrations, then commit and push the changes, requirements.txt included:

python manage.py makemigrations customers shop

customers gets its first migration. shop has no models yet, so Django reports No changes detected in app 'shop'. Commit the migration: without it, the Migrate job logs Your models in app(s): 'customers' have changes that are not yet reflected in a migration and fails with django.db.utils.ProgrammingError: relation "customers_client" does not exist.

Prepare the application on Sevalla

The Migrate job from the deploy guide needs no change: django-tenants replaces Django’s migrate command with its migrate_schemas, so python manage.py migrate --noinput migrates the public schema with the shared apps and every tenant’s schema with the tenant apps. Its output on the Logs tab starts each line with the schema, such as [standard:public].

Add the wildcard domain

In the sidebar, click Applications, then click the application. Click the Domains tab, then click Add custom domain. Enter shop.example.com as the Domain name, select Wildcard so that every subdomain such as acme.shop.example.com reaches the application too, and click Add custom domain. Add the DNS records that Sevalla shows at your DNS provider, including the pointing record for *.shop.example.com, and wait until the domain’s status is Active. See Wildcard domains.

Allow the subdomains

Click the Environment variables tab. Update ALLOWED_HOSTS to storefront-x7k2m.sevalla.app,.shop.example.com, with your application’s sevalla.app domain. The leading dot matches the domain and every subdomain.

Deploy

Click Deploy in the undeployed changes bar at the bottom of the page.

The Add custom domain sheet with a domain name field and a Wildcard option

Create the tenants

django-tenants serves a request only when its host belongs to a tenant, so create the public tenant for the main domain first. When the deployment’s status is Deployed, click the Web terminal tab, and in the shell that opens in the Web process, open a Django shell:

python manage.py shell

from customers.models import Client, Domain

public = Client.objects.create(schema_name="public", name="Shop platform")
Domain.objects.create(domain="shop.example.com", tenant=public, is_primary=True)

acme = Client.objects.create(schema_name="acme", name="Acme Inc")
Domain.objects.create(domain="acme.shop.example.com", tenant=acme, is_primary=True)

Saving acme creates the acme schema and runs the tenant apps’ migrations in it. Create every later tenant the same way, or from your own sign-up view. The application’s sevalla.app domain matches no tenant, so it returns 404. To show the public site there too, set SHOW_PUBLIC_IF_NO_TENANT_FOUND = True in storefront/settings.py.

Verify

Open https://shop.example.com: the page reads Shop platform.
Open https://acme.shop.example.com: the page reads Welcome to Acme Inc.

From a shell:

curl -s https://shop.example.com/; echo
curl -s https://acme.shop.example.com/; echo

Shop platform
Welcome to Acme Inc

Deploy with the API

This sequence prepares the application from Deploy with the API and continues in its shell, with API, APP_ID, WEB_ID and APP_HOST set. Push the code changes from Configure the project and Add the views and URLs first. Each step names the CLI command and the Sevalla MCP server tool that do the same.

Look up the process size

List process resource types (listProcessResourceTypesV3). Save S1:

S1_ID=$(curl -s "$API/resources/process-resource-types" -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.name == "s1") | .id')

CLI: sevalla resources process-types. MCP: get_platform_options.

Size the web process

Update process (updateProcessV3) moves the web process to S1, which can have custom domains:

curl -s -X PATCH "$API/applications/$APP_ID/processes/$WEB_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg size "$S1_ID" '{resource_type_id: $size}')" | jq -r .resource_type_name

It prints s1. CLI: sevalla apps processes update "$WEB_ID" --app-id "$APP_ID" --resource-type "$S1_ID". MCP: scale_process with size_id and apply_now: false.

Add the wildcard domain

Add application domain (addApplicationDomainV3) with is_wildcard:

curl -s -X POST "$API/applications/$APP_ID/domains" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"domain_name": "shop.example.com", "is_wildcard": true}' | jq -r .status

It prints VERIFICATION. CLI: sevalla apps domains add "$APP_ID" --name shop.example.com, which has no wildcard option. MCP: add_domain with wildcard: true.

Read the DNS records

List application domains (listApplicationDomainsV3) returns the records to add at your DNS provider a few seconds after the domain is added; until then, dns_records is null:

curl -s "$API/applications/$APP_ID/domains" -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq '.data[] | select(.name == "shop.example.com") | {status, verification: .dns_records.verification, origin: .dns_records.origin}'

verification holds a TXT record for _cf-custom-hostname.shop.example.com, and origin holds the records that point shop.example.com and *.shop.example.com at Sevalla. The status changes from VERIFICATION to POINTING once Sevalla has verified the domain, and to ACTIVE once the domain points at Sevalla. CLI: sevalla apps domains list --app-id "$APP_ID". MCP: get_application.

Find ALLOWED_HOSTS

List environment variables (listEnvironmentVariablesV3) returns each variable’s ID:

HOSTS_ID=$(curl -s "$API/applications/$APP_ID/env-vars" -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.key == "ALLOWED_HOSTS") | .id')

CLI: sevalla apps env-vars list --app-id "$APP_ID". MCP: list_environment_variables.

Allow the subdomains

Update environment variable (updateEnvironmentVariableV3):

curl -s -X PUT "$API/applications/$APP_ID/env-vars/$HOSTS_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg hosts "$APP_HOST,.shop.example.com" '{value: $hosts}')" | jq -r .key

CLI: sevalla apps env-vars update "$HOSTS_ID" --app-id "$APP_ID" --value "$APP_HOST,.shop.example.com". MCP: set_environment_variables, which updates a variable by its key.

Deploy

Trigger deployment (triggerDeploymentV3). With Auto-deploy on, the push already started a deployment; this one queues behind it:

DEPLOYMENT_ID=$(curl -s -X POST "$API/applications/$APP_ID/deployments" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" -d '{}' | jq -r .id)

CLI: sevalla apps deployments trigger "$APP_ID". MCP: trigger_deployment.

Wait for the deployment

Get deployment (getDeploymentV3) reports the status, which ends as success, failed, cancelled or skipped. The loop keeps polling through a failed request, for up to 30 minutes:

for i in $(seq 1 120); do
  STATUS=$(curl -s "$API/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

CLI: sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID". MCP: get_deployment.

Create the tenants

Run a command in a process (execProcessCommandV3) runs the code from Create the tenants in the web process. Creating a tenant’s schema takes a few seconds, so allow up to 60:

curl -s -X POST "$API/applications/$APP_ID/processes/$WEB_ID/exec" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"timeout": 60, "command": ["python", "manage.py", "shell", "-v", "0", "-c", "from customers.models import Client, Domain; public = Client.objects.create(schema_name=\"public\", name=\"Shop platform\"); Domain.objects.create(domain=\"shop.example.com\", tenant=public, is_primary=True); acme = Client.objects.create(schema_name=\"acme\", name=\"Acme Inc\"); Domain.objects.create(domain=\"acme.shop.example.com\", tenant=acme, is_primary=True)"]}' \
  | jq -r .exit_code

It prints 0. CLI:

sevalla apps processes exec "$WEB_ID" --app-id "$APP_ID" --timeout 60 -- python manage.py shell -v 0 -c "<the same code>"

. MCP: sevalla_api_update with execProcessCommandV3 and the same body.

When the domain’s status is ACTIVE, run the checks in Verify.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Build a multitenant Django application

At a glance

Environment variables

Before you begin

Install django-tenants

Add the tenant models

Configure the project

Add the views and URLs

Prepare the application on Sevalla

Create the tenants

Verify

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Install django-tenants

​Add the tenant models

​Configure the project

​Add the views and URLs

​Prepare the application on Sevalla

​Create the tenants

​Verify

​Deploy with the API

At a glance

Environment variables

Before you begin

Install django-tenants

Add the tenant models

Configure the project

Add the views and URLs

Prepare the application on Sevalla

Create the tenants

Verify

Deploy with the API