Django 6 – lokales Docker-Setup

Ein minimales Django-6-Projekt mit PostgreSQL und einer Hello-World-Seite. Das Setup ist für die lokale Entwicklung unter Ubuntu mit Docker ausgelegt. Es enthält noch keine eigenen Modelle.

Voraussetzungen

• Ubuntu oder eine vergleichbare Linux-Distribution
• Docker Engine
• Docker Compose Plugin (docker compose)

Prüfen, ob beides installiert ist:

docker --version
docker compose version

Python und PostgreSQL müssen nicht direkt auf dem Host installiert sein.

Projekt lokal starten

Im Projektverzeichnis ausführen:

docker compose up --build

Danach ist die Hello-World-Seite erreichbar unter:

http://localhost:8000

Beim ersten Start passiert automatisch Folgendes:

1. Das Django-Image wird gebaut.
2. PostgreSQL wird gestartet und auf Bereitschaft geprüft.
3. Die eingebauten Django-Migrationen werden ausgeführt.
4. Der Django Development Server startet auf Port 8000.

Mit Ctrl+C werden die laufenden Container beendet. Im Hintergrund starten:

docker compose up --build -d

Logs anzeigen:

docker compose logs -f web

Container stoppen:

docker compose down

Fehlerbehebung: DNS beim Image-Build

Die Meldung Temporary failure in name resolution bedeutet, dass Docker Domainnamen wie pypi.org nicht auflösen kann. Es handelt sich nicht um einen Django- oder pip-Fehler.

Zuerst prüfen, ob die Namensauflösung auf dem Ubuntu-Host funktioniert:

getent hosts pypi.org

Anschließend die Namensauflösung in einem Container testen:

docker run --rm busybox nslookup pypi.org

Funktioniert DNS auf dem Host, aber nicht im Container, können DNS-Server für den Docker-Daemon konfiguriert werden. Falls /etc/docker/daemon.json bereits existiert, vorhandene Einstellungen beibehalten und nur den Schlüssel dns ergänzen:

{
  "dns": ["1.1.1.1", "8.8.8.8"]
}

Danach Docker neu starten und das Image ohne alten Build-Cache bauen:

sudo systemctl restart docker
docker compose build --no-cache web
docker compose up

In Firmen-, VPN- oder Proxy-Netzwerken müssen gegebenenfalls die DNS- beziehungsweise Proxy-Vorgaben des Netzwerks verwendet werden. Öffentliche DNS-Server können dort gesperrt sein.

Automatisches Neuladen bei Codeänderungen

Das gesamte Projektverzeichnis ist als Bind Mount unter /app in den Web-Container eingebunden. Django läuft im Entwicklungsmodus mit seinem automatischen Reloader.

Änderungen an Python-, Template- oder CSS-Dateien stehen deshalb direkt im Container zur Verfügung. Bei Python-Änderungen startet Django den Development Server automatisch neu. Nach Änderungen an HTML oder CSS muss die Seite im Browser neu geladen werden.

Ein zusätzlicher Image-Build ist nur erforderlich, wenn sich requirements.txt oder der Dockerfile ändert:

docker compose up --build

Umgebungsvariablen

Das Projekt funktioniert ohne zusätzliche Konfiguration mit lokalen Standardwerten. Optional kann eine .env angelegt werden:

cp .env.example .env

Anschließend können in .env diese Werte angepasst werden:

DJANGO_SECRET_KEY=replace-me-for-local-development
POSTGRES_DB=django
POSTGRES_USER=django
POSTGRES_PASSWORD=django

Die .env wird durch .gitignore und .dockerignore ausgeschlossen und soll nicht versioniert werden.

Nützliche Befehle

Django-Systemprüfung ausführen:

docker compose exec web python manage.py check

Migrationen manuell ausführen:

docker compose exec web python manage.py migrate

Superuser ausschließlich über die CLI erstellen:

docker compose exec web python manage.py createsuperuser

Eine öffentliche Registrierung ist nicht vorhanden. Auch über die Admin-Oberfläche können keine weiteren Benutzer angelegt werden.

Django-Shell öffnen:

docker compose exec web python manage.py shell

Datenbank zurücksetzen

PostgreSQL-Daten bleiben im Docker-Volume postgres_data erhalten. Zum vollständigen Löschen der lokalen Datenbank:

docker compose down -v

Beim nächsten docker compose up wird die Datenbank neu angelegt.

Projektstruktur

.
├── compose.yaml
├── Dockerfile
├── manage.py
├── requirements.txt
├── accounts/
│   ├── admin.py
│   ├── apps.py
│   └── tests.py
├── config/
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
├── templates/
│   └── index.html
└── static/
    └── css/
        └── styles.css

Hinweis zum Einsatz

Die lokale Compose-Konfiguration verwendet weiterhin runserver und DEBUG=True. Das Dockerfile startet dagegen Gunicorn und ist für die Bereitstellung mit Coolify vorbereitet.

Deployment auf Coolify

1. PostgreSQL anlegen

In Coolify eine PostgreSQL-Ressource erstellen. Die Datenbank muss nicht öffentlich erreichbar sein. Anwendung und Datenbank müssen demselben Coolify-Projekt bzw. demselben Zielserver-Netzwerk zugeordnet sein.

2. Anwendung anlegen

Eine neue Anwendung aus diesem Git-Repository erstellen und als Build Pack Dockerfile wählen. Folgende Werte konfigurieren:

• Dockerfile: /Dockerfile
• Port: 8000
• Health Check Path: /
• Domain: die gewünschte Domain mit https://, zum Beispiel https://app.example.com

Coolify übernimmt Reverse Proxy und TLS. In der Anwendung wird kein zusätzlicher Nginx- oder Caddy-Container benötigt.

3. Umgebungsvariablen setzen

In Coolify unter Environment Variables konfigurieren:

DJANGO_SECRET_KEY=<langer-zufaelliger-wert>
DJANGO_DEBUG=False
POSTGRES_DB=django
DJANGO_ALLOWED_HOSTS=app.example.com
DJANGO_CSRF_TRUSTED_ORIGINS=https://app.example.com
POSTGRES_USER=django
POSTGRES_[PASSWORD] POSTGRES_HOST=<interner-coolify-datenbank-host>
POSTGRES_PORT=5432

Für POSTGRES_HOST den internen Hostnamen der Coolify-PostgreSQL-Ressource eintragen. localhost ist falsch, weil PostgreSQL in einem anderen Container läuft. Coolify zeigt den Host bei den internen Verbindungsdaten der PostgreSQL-Ressource an.

4. Deployen

Beim Containerstart werden Migrationen und collectstatic automatisch ausgeführt; anschließend startet Gunicorn auf Port 8000. Nach dem ersten erfolgreichen Deployment kann in Coolifys Terminal ein Administrator erstellt werden:

python manage.py createsuperuser

Vor Updates sollte über die Coolify-PostgreSQL-Ressource ein Backup eingerichtet und dessen Wiederherstellung getestet werden.