Deploy a Django app with Postgres on your own server (and fix the 4 errors everyone hits)

[thegdsks]

By the end of this post you will have a Django app running on your own Linux box, talking to a managed Postgres 16, with migrations applied, secrets stored encrypted, health checks passing and one-command rollback. Along the way I hit the four errors that cost most Django developers an afternoon on a first container deploy: a process that dies in under a second, a refused ALLOWED_HOSTS, a readiness probe that gets a 400, and a readiness probe that never gets a 200 because of SECURE_SSL_REDIRECT. Each one gets its symptom, its cause and its fix.

The commands use levelrail-cli against a control plane you already have running. If you do not have one yet, start with Getting started and Installing.

Contents

• Pre-flight checklist
• How the pieces fit
• Make Django container friendly
• Import the repo
• Postgres and DATABASE_URL
• Secrets and migrations
• Troubleshooting: the four errors
• Logs, rollback, domains
• Next steps

Pre-flight checklist

• A Levelrail control plane is up and levelrail-cli can reach it
• Your Django project is in a GitHub repo the control plane can clone
• requirements.txt lists django, gunicorn, whitenoise, dj-database-url and psycopg[binary]
• Your project package is called config (adjust config.wsgi below if it is not)
• You know the hostname you will serve from, or you are happy to test on the server IP first

How the pieces fit

flowchart LR
    A[git repo] -->|analyze + build| B[Levelrail control plane]
    B -->|image| C[Django container<br/>gunicorn + whitenoise]
    B -->|creates| D[(Postgres 16<br/>managed database)]
    D -->|DATABASE_URL injected| C
    E[Browser] -->|HTTPS| F[Caddy ingress]
    F -->|HTTP + X-Forwarded-Proto| C
    B -->|readiness probe<br/>Host: 127.0.0.1:PORT| C

Loading

Two details in that picture explain most of the pain. TLS ends at the ingress, so Django sees plain HTTP and has to be told to trust the forwarded protocol header. And the readiness probe talks to the container directly, by IP, so the Host header it sends is 127.0.0.1:<port> (the address it dials). Django rejects that host unless you plan for it.

Make Django container friendly

A container gets its configuration from environment variables, so settings should read them and fail loudly when something is missing. Everything below is a baseline you can paste into a fresh startproject layout.

# config/settings.py
import os
from pathlib import Path

import dj_database_url
from django.core.exceptions import ImproperlyConfigured

BASE_DIR = Path(__file__).resolve().parent.parent


def env_list(name: str) -> list[str]:
    return [v.strip() for v in os.environ.get(name, "").split(",") if v.strip()]


SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY")
if not SECRET_KEY:
    raise ImproperlyConfigured("Set the DJANGO_SECRET_KEY environment variable")

DEBUG = os.environ.get("DJANGO_DEBUG", "0") == "1"

ALLOWED_HOSTS = env_list("DJANGO_ALLOWED_HOSTS")
if not DEBUG and (not ALLOWED_HOSTS or "*" in ALLOWED_HOSTS):
    raise ImproperlyConfigured("Set DJANGO_ALLOWED_HOSTS to explicit production hosts")

CSRF_TRUSTED_ORIGINS = env_list("DJANGO_CSRF_TRUSTED_ORIGINS")

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",  # right after SecurityMiddleware
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
]

ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

DATABASES = {
    "default": dj_database_url.config(
        env="DATABASE_URL",
        default=f"sqlite:///{BASE_DIR / 'db.sqlite3'}",
        conn_max_age=60,
    )
}

STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
STORAGES = {
    "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    "staticfiles": {
        "BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"
    },
}

if not DEBUG:
    SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
    SECURE_SSL_REDIRECT = True
    SECURE_REDIRECT_EXEMPT = [r"^healthz/$"]
    SESSION_COOKIE_SECURE = True
    CSRF_COOKIE_SECURE = True

A few choices worth explaining:

• The secret key has no default. A default key that ships in the repo is a vulnerability you will forget about. Crashing at startup is the right behavior, and error 1 below shows exactly what that crash looks like.
• SECURE_PROXY_SSL_HEADER is only safe behind a proxy you control. The Django settings reference says the proxy must strip the header from incoming requests and set it only for requests that arrived over HTTPS. The Levelrail ingress sits in that position, so the setting is safe here.
• SECURE_REDIRECT_EXEMPT patterns must not start with a slash. Django's docs say SecurityMiddleware strips leading slashes from the path before matching, so the pattern is ^healthz/$, not ^/healthz/$. Get this wrong and the exemption silently never matches.
• STORAGES replaces the default dict, it does not merge. That is why the default entry is spelled out. The staticfiles backend is the one WhiteNoise recommends for compression and cache-busting filenames.

A health endpoint

# config/urls.py
from django.contrib import admin
from django.db import connection
from django.http import HttpResponse, JsonResponse
from django.urls import path


def healthz(request):
    try:
        with connection.cursor() as cur:
            cur.execute("SELECT 1")
    except Exception:
        return JsonResponse({"status": "db_unavailable"}, status=503)
    return HttpResponse("ok")


urlpatterns = [
    path("healthz/", healthz),
    path("admin/", admin.site.urls),
]

It checks the database, so a deploy that cannot reach Postgres never becomes ready. Keep it cheap: one SELECT 1, no ORM models, no auth.

Start command and static files

# Procfile
web: gunicorn config.wsgi --bind 0.0.0.0:${PORT:-8000}

Bind to 0.0.0.0, not 127.0.0.1. A process listening only on loopback inside the container is unreachable from the probe and the ingress. The ${PORT:-8000} default keeps the command working when no port is injected.

WhiteNoise serves files out of STATIC_ROOT, so something has to fill it, and its docs are blunt about it: run python manage.py collectstatic --noinput before the app starts. Put that in your build step or Dockerfile. If you use CompressedManifestStaticFilesStorage and skip it, any template that calls {% static %} raises at render time, which shows up as a 500 on the first page that uses CSS.

Tip

In a Dockerfile, collectstatic needs settings to import, and ours demand a secret key. A throwaway on that one line works and never reaches the running container's environment: RUN DJANGO_SECRET_KEY=build DJANGO_DEBUG=1 python manage.py collectstatic --noinput.

Import the repo

Analyze first. This changes nothing, it only shows what Levelrail inferred:

levelrail-cli import https://github.com/OWNER/REPO --analyze --name shop

The result is a table of detections, each with the evidence behind it: stack, build type, port, health path, environment keys and databases. Levelrail reads manifest files such as requirements.txt and pyproject.toml and knows Django, so expect a Railpack build for the Python (Django) provider; the importing apps page lists what it looks at. If a row is wrong, override it with --build-type, --dockerfile or --base-directory and analyze again.

When the table looks right, apply:

levelrail-cli import https://github.com/OWNER/REPO --apply --name shop

--apply creates the suggested databases, the app, the repository link and the first build in one go. Add --no-database if you would rather bring your own Postgres.

Expect the first deploy to fail if your settings insist on a secret key, as ours do. You have not set the secrets yet, and that failure is error 1 below.

Postgres and DATABASE_URL

When the analysis finds a Postgres dependency, --apply creates a managed database and attaches it to the app, with its connection string injected as DATABASE_URL. You never copy a password around. Levelrail's Postgres accepts TLS, and the injected URL carries ?sslmode=require. That is the reason to feed it to dj-database-url instead of a hand-rolled parser that drops query parameters: the library turns the query string into the right OPTIONS entry for you.

Check the database any time:

levelrail-cli databases get shop-postgres

The database name in that command is whatever --apply created, so read it from the import output if yours differs. See Connecting apps to databases for naming and for attaching more than one.

Secrets and migrations

Set the values the app refuses to boot without. --apply restarts the app so the new value reaches the running container:

levelrail-cli apps secrets set shop DJANGO_SECRET_KEY "$(python -c 'import secrets; print(secrets.token_urlsafe(64))')" --apply
levelrail-cli apps secrets set shop DJANGO_ALLOWED_HOSTS "shop.example.com,127.0.0.1" --apply
levelrail-cli apps secrets set shop DJANGO_CSRF_TRUSTED_ORIGINS "https://shop.example.com" --apply

Values are encrypted at rest and never printed back; apps secrets list shop shows key names only. DJANGO_ALLOWED_HOSTS is not really a secret, but setting it the same way keeps all configuration in one place. The 127.0.0.1 is deliberate, and error 3 explains why.

Once the app is running, apply migrations inside the container so they run against the real database with the real environment:

levelrail-cli apps exec shop -- python manage.py migrate
levelrail-cli apps exec shop -- python manage.py createsuperuser

apps exec exits with the command's own exit code, so it is safe in scripts and CI.

Note

Levelrail's deploying apps page says the Railpack Django build runs python manage.py migrate on start. Running it by hand is still the way to see the output and to be sure. If you use your own Dockerfile, you own that step.

Troubleshooting: the four errors

All four came up while deploying a real Django app end to end, in this order.

1. The container exits in about 700 ms

Symptom. levelrail-cli apps status shop shows ExitedDuringReadiness. levelrail-cli apps diagnose shop reports CRASHLOOP_GENERIC, which tells you nothing you did not already know.

Cause. Python died while importing settings, before gunicorn bound a port. The reason is in the logs, not the diagnosis:

levelrail-cli apps logs shop

What the log shows

django.core.exceptions.ImproperlyConfigured: Set the DJANGO_SECRET_KEY environment variable

A traceback through config/settings.py precedes that line. A process that dies in well under a second almost always failed at import time, which for Django means settings.

Fix. Set the secret as shown above. When status says the container exited during readiness, read apps logs first and apps diagnose second.

2. "Set DJANGO_ALLOWED_HOSTS to explicit production hosts"

Symptom. You tried DJANGO_ALLOWED_HOSTS=* to get past the next error, and the app now refuses to start with that message.

Cause. The settings above reject a wildcard when DEBUG is off, on purpose. Per the Django docs, '*' matches anything and leaves you responsible for validating the Host header yourself, and that validation is what protects password reset links from host header poisoning.

Fix. Use an explicit comma separated list. It is the only form that passes the check:

levelrail-cli apps secrets set shop DJANGO_ALLOWED_HOSTS "shop.example.com,127.0.0.1" --apply

3. Readiness probe returns 400

Symptom. The container stays up, but status shows a message of the form GET http://127.0.0.1:<port>/healthz/ returned 400, expected 200-299.

Cause. The probe dials the container by IP, so the request carries Host: 127.0.0.1:<port>. With DEBUG off, that host is not in ALLOWED_HOSTS, get_host() raises DisallowedHost, and Django answers 400. With DEBUG on and an empty ALLOWED_HOSTS, Django validates against .localhost, 127.0.0.1 and [::1] instead, which is why it worked on your laptop. Any platform that probes by IP runs into this, not only this one.

Fix, option A. Put 127.0.0.1 in DJANGO_ALLOWED_HOSTS, as in the command above. Django matches hosts without the port. It costs you nothing, because a request that reaches the container's own loopback address is already inside the container.

Fix, option B. Tell the probe which host to send, using your real domain:

levelrail-cli apps health set shop --probe readiness --path /healthz/ --host shop.example.com
levelrail-cli apps restart shop

B keeps the allow list tight but ties the probe to a domain. A is quicker for a first deploy, B is tidier once the hostname is stable.

4. Readiness never goes green because of a redirect

Symptom. Hosts are right, yet readiness keeps failing against / or any path you did not exempt.

Cause. SECURE_SSL_REDIRECT = True makes Django answer every plain HTTP request with a 301 to HTTPS. The probe is plain HTTP and sends no X-Forwarded-Proto, so it gets redirected. By default the probe follows redirects, which sends it to an https:// URL on a port that only speaks HTTP, so the attempt fails. With redirects turned off you get returned 301 to ...; set follow_redirects or expected_status instead. Either way it is the same cause.

Fix. Point the probe at the path you exempted with SECURE_REDIRECT_EXEMPT, restart, and check:

levelrail-cli apps health set shop --probe readiness --path /healthz/
levelrail-cli apps restart shop
levelrail-cli apps status shop

In my run, status went to Ready True with reason AlreadyRunning after this change.

Important

apps health set changes the probe you name. Setting readiness does not touch liveness, so set both if you want both on /healthz/.

levelrail-cli apps health discover shop tries well known paths and shows what each returns, which is a quick way to confirm the exempt path really answers 200.

Logs, rollback, domains

Logs. Search stored entries, or follow live:

levelrail-cli apps logs shop
levelrail-cli apps logs shop --follow

Rollback. Each deploy keeps the previous image pinned, so garbage collection cannot remove your way back. Roll back to an older, already-built image:

levelrail-cli apps rollback shop --image <previous-image-ref>

levelrail-cli apps images shop lists the tags you can pick from. A rollback does not undo migrations. Write them to be backward compatible for one release (add columns as nullable, drop them a deploy later) and rollback stays safe. Details in Rollback.

Domains. Point a DNS record at the server, then attach it:

levelrail-cli apps domains add shop shop.example.com --wait

--wait prints each go-live step and exits non-zero if the domain is not live in time. Certificates are issued automatically. Make sure the domain is also in DJANGO_ALLOWED_HOSTS and, with its scheme, in DJANGO_CSRF_TRUSTED_ORIGINS, or login forms fail with a CSRF error. More in Domains and ingress.

Quick reference

Symptom	Where to look	Fix
Exit in under a second	apps logs	Set the missing env var
Wildcard host refused	apps logs	Explicit host list
Probe 400	apps status	Add 127.0.0.1 or set probe --host
Probe redirect or 301	apps status	Probe an exempt path
Login CSRF error	browser	Set DJANGO_CSRF_TRUSTED_ORIGINS

Next steps

• Add a liveness probe on /healthz/ with apps health set shop --probe liveness --path /healthz/
• Read the CLI reference for scheduled tasks, previews and alerts
• Describe the app in a file with the app spec reference so the deploy is reviewable in git

If this saved you an afternoon, a star on the repo helps other Django developers find it. If you hit a fifth error, drop it in the comments with your apps status and apps logs output and I will add it to the table.

Django references used above: SECURE_PROXY_SSL_HEADER, SECURE_REDIRECT_EXEMPT and WhiteNoise with Django.