Python-App deployen: Gunicorn und Nginx auf dem Server
Python-App deployen mit Flask oder Django: venv, Gunicorn, systemd-Dienst, Nginx als Reverse Proxy, statische Dateien, HTTPS, Updates und typische Fehler.

Inhalt
- Voraussetzungen
- Schritt 1: Python, venv und Nginx
- Schritt 2: Benutzer, Code und virtuelle Umgebung
- Schritt 3: Gunicorn testen
- Schritt 4: Umgebungsvariablen
- Schritt 5: Django-Produktionseinstellungen
- Schritt 6: systemd-Dienst für Gunicorn
- Schritt 7: Nginx als Reverse Proxy
- Schritt 8: HTTPS
- Updates deployen
- Logs und typische Fehler
- Ein Hinweis zu FastAPI
- Nodesty Server für Python-Apps
Wer eine Python-App deployen möchte, etwa ein Flask- oder Django-Projekt, braucht mehr als den Entwicklungsserver: eine virtuelle Umgebung für die Abhängigkeiten, Gunicorn als Anwendungsserver, systemd, das ihn am Laufen hält, und davor Nginx für HTTPS und statische Dateien. Steht dieses Setup einmal, besteht jedes Update nur noch aus einer Handvoll Befehle.
In dieser Anleitung zeigen wir, wie Sie eine Flask- oder Django-Anwendung auf einem frischen Ubuntu-Server deployen: Server vorbereiten, Gunicorn testen, den systemd-Dienst schreiben, Nginx konfigurieren, Django-Produktionseinstellungen, HTTPS, Updates und die häufigsten Fehler.
Voraussetzungen
- Server: Ein Ubuntu-Server mit Root-Zugriff. In dieser Anleitung verwenden wir Ubuntu 24.04.
- Anwendung: Ein Flask- oder Django-Projekt in einem Git-Repository mit einer Datei
requirements.txt. - Datenbank: Falls Ihre App eine nutzt, lesen Sie unsere Anleitung PostgreSQL installieren.
- Domain: Ein A-Eintrag, der auf die IP-Adresse Ihres Servers zeigt.
Schritt 1: Python, venv und Nginx
Nachdem Sie sich per SSH mit Ihrem Server verbunden haben:
sudo apt update
sudo apt install python3 python3-venv python3-pip nginx git
Unter AlmaLinux lautet der entsprechende Befehl sudo dnf install python3 python3-pip nginx git; das Modul venv ist dort bereits in python3 enthalten. Nginx läuft als Benutzer nginx statt www-data, und Site-Dateien gehören nach /etc/nginx/conf.d/. Die Grundlagen finden Sie in unserer Anleitung Nginx installieren.
Schritt 2: Benutzer, Code und virtuelle Umgebung
Führen Sie die Anwendung nicht als root aus. Legen Sie dafür einen Benutzer, einen Ordner unter /srv und darin eine virtuelle Umgebung an:
sudo adduser --disabled-password --gecos "" deploy
sudo mkdir -p /srv/app
sudo chown deploy:deploy /srv/app
sudo -iu deploy
git clone git@github.com:user/app.git /srv/app
cd /srv/app
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt gunicorn
Die virtuelle Umgebung hält Ihre Pakete vom System-Python getrennt; Ubuntu 24.04 blockiert pip install außerhalb einer venv ohnehin (Fehler „externally-managed-environment“). Wenn Sie Django mit PostgreSQL nutzen, achten Sie darauf, dass psycopg in der requirements.txt steht. Deploy Keys behandeln wir in unserer Anleitung Deployment mit Git, die Benutzerverwaltung in Linux-Benutzer anlegen. Führen Sie die Befehle der folgenden Schritte als Benutzer deploy aus, sofern sie nicht mit sudo beginnen.
Schritt 3: Gunicorn testen
Prüfen Sie, bevor Sie eine Dienstdatei schreiben, ob Gunicorn die App laden kann. Das Argument hat die Form modul:variable:
# Flask: app.py enthält app = Flask(__name__)
gunicorn --bind 127.0.0.1:8000 app:app
# Django: der Projektordner, der wsgi.py enthält
gunicorn --bind 127.0.0.1:8000 project.wsgi:application
Aus einer zweiten SSH-Sitzung sollte curl -I http://127.0.0.1:8000 eine Antwort liefern. Nutzt Ihre Flask-App eine Application Factory, schreiben Sie "app:create_app()". Beenden Sie Gunicorn mit Strg+C.
Im Produktivbetrieb kommt es auf zwei Einstellungen an:
- Worker: Als Faustregel gilt
2 × CPU-Kerne + 1; die Zahl der Kerne zeigtnproc. Jeder Worker ist ein eigener Prozess, mehr Worker bedeuten also auch mehr RAM. - Timeout: Gunicorn startet einen Worker, der nicht innerhalb von 30 Sekunden antwortet, standardmäßig neu. Erhöhen Sie den Wert mit
--timeout 60nur, wenn Sie wirklich langsame Anfragen haben; lange Aufgaben gehören in eine Hintergrund-Queue.
Schritt 4: Umgebungsvariablen
Halten Sie Geheimnisse aus dem Code und dem Repository heraus. Erzeugen Sie mit python3 -c "import secrets; print(secrets.token_urlsafe(50))" einen geheimen Schlüssel ohne Zeichen, die in der Datei Probleme machen, und legen Sie mit Ihrem Admin-Konto die Datei /etc/app.env an:
DJANGO_SECRET_KEY=hier-den-erzeugten-wert-einfuegen
DB_PASSWORD=ein-starkes-passwort
Schreiben Sie pro Zeile ein SCHLÜSSEL=wert, ohne export und ohne Leerzeichen um das =. Schützen Sie die Datei anschließend mit sudo chown root:deploy /etc/app.env und sudo chmod 640 /etc/app.env, und lesen Sie die Werte im Code mit os.environ aus.
Schritt 5: Django-Produktionseinstellungen
Bei Flask überspringen Sie diesen Schritt. Ändern Sie in der settings.py mindestens diese Werte:
import os
DEBUG = False
SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]
ALLOWED_HOSTS = ["example.com", "www.example.com"]
CSRF_TRUSTED_ORIGINS = ["https://example.com", "https://www.example.com"]
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
STATIC_URL = "/static/"
STATIC_ROOT = BASE_DIR / "staticfiles"
DEBUG = False: Ist der Debug-Modus aktiv, zeigen Fehlerseiten Besuchern Ihre Einstellungen und Ihren Code.ALLOWED_HOSTS: Anfragen für jeden anderen Hostnamen erhalten einen 400-Fehler (DisallowedHost).CSRF_TRUSTED_ORIGINSundSECURE_PROXY_SSL_HEADER: Hinter Nginx sieht Django nur einfaches HTTP. Mit diesen Einstellungen vertraut es dem HeaderX-Forwarded-Proto, sodass Formulare über HTTPS funktionieren. Verwenden Sie die Header-Einstellung nur, wenn Nginx den Header wie unten setzt.
Laden Sie anschließend die Variablen in Ihre Shell und bereiten Sie Datenbank und statische Dateien vor:
set -a; . /etc/app.env; set +a
python manage.py migrate
python manage.py collectstatic --noinput
Schritt 6: systemd-Dienst für Gunicorn
Verlassen Sie die deploy-Shell mit exit und legen Sie die Datei /etc/systemd/system/app.service an:
[Unit]
Description=Gunicorn for app
After=network.target
[Service]
User=deploy
Group=www-data
WorkingDirectory=/srv/app
EnvironmentFile=/etc/app.env
RuntimeDirectory=app
ExecStart=/srv/app/venv/bin/gunicorn --workers 3 --timeout 60 \
--access-logfile - --bind unix:/run/app/gunicorn.sock project.wsgi:application
Restart=always
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now app
ExecStart nutzt den vollständigen Pfad zum gunicorn der venv, Sie müssen also nichts aktivieren. RuntimeDirectory legt /run/app bei jedem Start an. Für Flask ersetzen Sie das letzte Argument durch app:app. Bevorzugen Sie TCP, verwenden Sie hier --bind 127.0.0.1:8000 und in Nginx proxy_pass http://127.0.0.1:8000;. Unit-Dateien erklären wir in unserer Anleitung systemd-Service erstellen.
Schritt 7: Nginx als Reverse Proxy
Legen Sie die Datei /etc/nginx/sites-available/app an:
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
client_max_body_size 20M;
location /static/ {
alias /srv/app/staticfiles/;
}
location / {
proxy_pass http://unix:/run/app/gunicorn.sock;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
sudo ln -s /etc/nginx/sites-available/app /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
aliasliefert statische Dateien direkt von der Festplatte aus, ohne Umweg über Python. Behalten Sie die abschließenden Schrägstriche auf beiden Seiten bei.client_max_body_size: Nginx erlaubt standardmäßig Uploads bis 1 MB; größere Dateien erhalten einen 413-Fehler.- Unter Flask umhüllen Sie die App mit
ProxyFixvon Werkzeug, damit sie diesen Headern beim Erzeugen von URLs vertraut.
Öffnen Sie in der Firewall nur die Web-Ports mit sudo ufw allow 'Nginx Full'; Port 8000 bleibt geschlossen. Mehr dazu in unserer Anleitung UFW Firewall.
Schritt 8: HTTPS
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com -d www.example.com
Certbot holt das Zertifikat, ergänzt den HTTPS-Serverblock und richtet die automatische Verlängerung ein. Details finden Sie in unserem Artikel Was ist ein SSL-Zertifikat?.
Updates deployen
sudo -iu deploy
cd /srv/app
git pull
source venv/bin/activate
pip install -r requirements.txt
set -a; . /etc/app.env; set +a
python manage.py migrate
python manage.py collectstatic --noinput
exit
sudo systemctl restart app
Gunicorn hält den alten Code bis zum Neustart im Speicher. Sichern Sie die Datenbank vor Migrationen, die Daten verändern; siehe unsere Anleitung Server-Backup.
Logs und typische Fehler
Die Ausgabe von Gunicorn landet im Journal (sudo journalctl -u app -f), Nginx schreibt nach /var/log/nginx/error.log.
| Fehler | Häufige Ursache |
|---|---|
| 502 Bad Gateway | Gunicorn läuft nicht, oder Nginx kann den Socket nicht öffnen (etwa ein Socket in /home/deploy) |
| Statische Dateien liefern 404 | collectstatic wurde nicht ausgeführt oder der alias-Pfad passt nicht zu STATIC_ROOT |
| 400 Bad Request, DisallowedHost | Die Domain fehlt in ALLOWED_HOSTS |
| 403 CSRF verification failed | In CSRF_TRUSTED_ORIGINS fehlt der https://-Origin |
| ModuleNotFoundError | Das Paket fehlt in der venv, oder der Dienst nutzt ein gunicorn außerhalb von /srv/app/venv |
Startet der Dienst nicht, zeigt journalctl meist den Python-Traceback; ein KeyError: 'DJANGO_SECRET_KEY' bedeutet, dass die EnvironmentFile nicht geladen wurde. Eine Schritt-für-Schritt-Checkliste für 502-Fehler finden Sie in unserer Anleitung 502 Bad Gateway beheben.
Ein Hinweis zu FastAPI
FastAPI und andere ASGI-Apps benötigen einen ASGI-Worker. Installieren Sie uvicorn in der venv und ändern Sie den Gunicorn-Befehl in gunicorn -k uvicorn.workers.UvicornWorker main:app; neuere Uvicorn-Versionen lagern diesen Worker in das separate Paket uvicorn-worker aus (-k uvicorn_worker.UvicornWorker). Alternativ starten Sie direkt uvicorn main:app --workers 4 --uds /run/app/gunicorn.sock. Nginx und systemd bleiben unverändert.
Nodesty Server für Python-Apps
Die AMD Ryzen 9 9950X vServer von Nodesty sorgen mit hoher Single-Core-Leistung für kurze Antwortzeiten bei Python-Anfragen; die AMD EPYC 7763 vServer bieten viele Kerne und viel RAM, um zusätzliche Gunicorn-Worker, die Datenbank und Hintergrundjobs auf demselben Server zu betreiben. Mit vollem Root-Zugriff, NVMe-Speicher, DDoS-Schutz durch nShield und kostenlosen täglichen Backups mit 7 Tagen Aufbewahrung bringen Sie Ihre Flask-, Django- oder FastAPI-Projekte sicher online.
Häufig gestellte Fragen
Warum starte ich auf dem Server nicht einfach python app.py oder manage.py runserver?
Der eingebaute Server von Flask und runserver von Django sind Entwicklungsserver. Sie sind weder auf Sicherheit noch auf Leistung unter echtem Traffic ausgelegt. Gunicorn betreibt mehrere Worker-Prozesse, startet abgestürzte Worker neu und arbeitet problemlos hinter Nginx, das sich um HTTPS, statische Dateien und langsame Clients kümmert.
Wie viele Gunicorn-Worker sollte ich verwenden?
Ein üblicher Ausgangswert sind zwei Worker pro CPU-Kern plus eins, also 5 Worker auf einem Server mit 2 Kernen. Jeder Worker ist ein eigener Prozess mit eigenem Speicher; behalten Sie daher den RAM-Verbrauch im Blick und senken Sie die Zahl, sobald der Server swappt. Messen Sie unter echter Last und passen Sie den Wert dann an.
Soll Gunicorn auf einem Unix-Socket oder auf 127.0.0.1:8000 lauschen?
Beides funktioniert. Ein Unix-Socket umgeht den TCP-Stack und ist aus dem Netzwerk überhaupt nicht erreichbar, während sich 127.0.0.1:8000 leichter mit curl testen lässt und keine Probleme mit Socket-Rechten verursacht. Binden Sie Gunicorn im Produktivbetrieb nie an 0.0.0.0; zum Internet hin sollte nur Nginx erreichbar sein.
Warum zeigt meine Website den Fehler 502 Bad Gateway?
Nginx kann Gunicorn nicht erreichen. Entweder läuft der Gunicorn-Dienst nicht, er ist beim Start abgestürzt oder Nginx darf den Socket nicht öffnen. Prüfen Sie zuerst systemctl status und journalctl für den Gunicorn-Dienst und danach das Nginx-Fehlerlog unter /var/log/nginx/error.log.
Kann ich eine FastAPI-App auf dieselbe Weise deployen?
Ja. FastAPI ist ein ASGI-Framework und läuft daher mit Uvicorn-Workern unter Gunicorn oder direkt mit Uvicorn. Der Rest der Einrichtung, also virtuelle Umgebung, systemd-Dienst, Nginx als Reverse Proxy und HTTPS, bleibt gleich.
Über den Autor
Nodesty-Team · Infrastruktur und Support
Das Nodesty-Team betreibt unsere Server, unser Netzwerk und unseren DDoS-Schutz im Alltag und beantwortet Support-Anfragen rund um die Uhr. Diese Ratgeber entstehen aus dieser Arbeit.
Verwandte Artikel

LEMP-Stack installieren: Nginx, MariaDB und PHP-FPM
LEMP-Stack installieren unter Ubuntu und Debian: Nginx, MariaDB und PHP-FPM, Server Block, PHP-Socket, Dateirechte, HTTPS und typische Fehler.

tmux Anleitung: Programme nach dem SSH-Logout weiterlaufen lassen
tmux Anleitung: Programme nach dem SSH-Logout weiterlaufen lassen, Sitzungen trennen und fortsetzen, Panes, Scrollen, .tmux.conf und typische Fehler.

Node.js-App deployen: PM2 und Nginx auf dem Server
Node.js-App deployen auf dem Linux-Server: Node.js LTS, npm ci, PM2 mit Autostart und Reload, Nginx als Reverse Proxy, HTTPS, Updates und typische Fehler.