Déploiement

Exécuter l'admin derrière un reverse proxy change deux points que vous pouvez sinon ignorer en développement local : la secret key doit être stable entre les processus worker, et les URL générées doivent refléter HTTPS même si votre application ne voit jamais que du HTTP simple en provenance du proxy.

import os

from sqlalchemy import create_engine
from starlette.applications import Starlette
from starlette_admin.contrib.sqla import Admin, ModelView

from myapp.models import Post

engine = create_engine(os.environ["DATABASE_URL"])
app = Starlette()

admin = Admin(
    engine,
    title="My Admin",
    base_url="/admin",
    secret_key=os.environ["ADMIN_SECRET_KEY"],
)
admin.add_view(ModelView(Post))
admin.mount_to(app)

uvicorn myapp.main:app --forwarded-allow-ips='*' --proxy-headers

Secret key

Admin génère une secret_key aléatoire au démarrage lorsque vous n'en fournissez pas. C'est acceptable pour un processus local unique, mais chaque processus worker génère sa propre clé de manière indépendante ; un jeton CSRF signé par un worker ne sera donc pas validable par un autre. Définissez secret_key à partir d'une variable d'environnement avant d'exécuter plusieurs processus. Consultez Security pour le détail complet des défaillances en mode multi-worker et pour comprendre comment la clé est utilisée.

Reverse proxy et HTTPS

Admin construit chaque lien interne (pages de liste, formulaires d'édition, exports, le mount /static, fichiers téléversés servis via /_files/...) en appelant request.url_for(...), dont le schéma est déduit de la requête entrante. Lorsqu'un proxy tel que Nginx, Caddy ou Traefik termine TLS et transmet du HTTP simple à votre application, Starlette ne peut pas savoir que la requête d'origine était en HTTPS, sauf si le proxy envoie X-Forwarded-Proto et que votre serveur ASGI lui fait confiance. Sans cette configuration, les liens générés rétrogradent en http://, ce que les navigateurs bloquent ou réécrivent lorsque la page elle-même a été chargée en HTTPS.

Corrigez cela à deux endroits :

1. Le proxy transmet l'en-tête :

   nginx

   location /admin/ {
       proxy_pass http://127.0.0.1:8000/admin/;
       proxy_set_header Host $host;
       proxy_set_header X-Forwarded-Proto $scheme;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
   }
   

2. Uvicorn lui fait confiance, via --proxy-headers accompagné de --forwarded-allow-ips désignant l'IP du proxy (ou '*' si le proxy n'est joignable que depuis l'intérieur de votre réseau) :

   uvicorn myapp.main:app --forwarded-allow-ips='*' --proxy-headers
   

Le worker uvicorn.workers.UvicornWorker de Gunicorn lit les deux mêmes paramètres depuis --forwarded-allow-ips. Consultez la documentation de déploiement d'Uvicorn pour l'ensemble des options relatives aux gestionnaires de processus.

Fichiers statiques

Les CSS et JS de l'admin sont livrés au sein du package starlette_admin, et Admin les sert lui-même via un mount /static sous base_url plutôt que depuis un hôte statique distinct. Le paramètre static_dir permet uniquement de remplacer certains fichiers (voir Templates), il ne déplace pas la distribution des assets hors du processus de votre application. Aucune option intégrée ne permet de servir ces fichiers depuis un CDN. Si vous en avez besoin, ajoutez plutôt une règle Cache-Control adaptée à la mise en cache pour {base_url}/static/* au niveau du proxy.

Les fichiers téléversés fonctionnent différemment : LocalStorage les sert également via l'application (/_files/{storage}/{path}, de sorte que le middleware d'authentification reste appliqué), mais S3Storage et autres backends distants peuvent être servis directement par le fournisseur. Consultez File Storage.

Et ensuite ?

• Security : Le piège de la secret_key en multi-worker en détail, ainsi que tout ce que les protections intégrées couvrent — et ne couvrent pas.
• Authentication : Contrôlez l'accès à l'admin avant qu'il ne soit accessible en production.
• File Storage : Configuration de S3Storage et des autres backends distants.