# Deploy Django

Deploy a Django app to Wokku with Postgres, automatic migrations, and static
files served via WhiteNoise.

Prerequisites

• A Wokku account and a connected server
• An SSH key registered for git push
• A Django project with requirements.txt

1. Create the app

wokku apps:create my-django-app --server my-server

2. Prepare your Django app

The Python buildpack detects requirements.txt. Make sure these are present:

# requirements.txt
django
gunicorn
psycopg[binary]
whitenoise
dj-database-url

Add a Procfile:

web: gunicorn myproject.wsgi --log-file -
release: python manage.py migrate --noinput

In settings.py, read the database + host from the environment and let
WhiteNoise serve static files:

import dj_database_url, os
DATABASES = {"default": dj_database_url.config(conn_max_age=600)}
ALLOWED_HOSTS = os.environ.get("ALLOWED_HOSTS", "").split(",")
MIDDLEWARE = ["whitenoise.middleware.WhiteNoiseMiddleware", *MIDDLEWARE]
STATIC_ROOT = BASE_DIR / "staticfiles"

3. Set environment variables

wokku config:set my-django-app \
  SECRET_KEY="$(python -c 'import secrets;print(secrets.token_urlsafe(50))')" \
  DJANGO_SETTINGS_MODULE=myproject.settings \
  ALLOWED_HOSTS=my-django-app.wokku.app DEBUG=False

4. Add a database

wokku addons:create postgres my-django-app

Wokku injects DATABASE_URL; dj-database-url reads it automatically. See
Create & Link a Database.

5. Deploy

git remote add wokku git@git.wokku.cloud:my-django-app
git push wokku main

git remote add wokku git@git.wokku.cloud:my-django-app
git push wokku main

Live at https://my-django-app.wokku.app.

6. Custom domain

Custom Domains — remember to add the new
hostname to ALLOWED_HOSTS and redeploy.

Troubleshooting

• DisallowedHost — add your domain to ALLOWED_HOSTS and redeploy.
• CSS/JS 404 in production — confirm WhiteNoise middleware + STATIC_ROOT; collectstatic must succeed in the build log.
• Migrations didn’t run — check the release: line and the deploy logs.

Next steps

• Background workers (Celery)
• Logs · Production Readiness