Premiers pas avec l'hébergement

Ce que vous saurez faire

Sachez exactement ce qu’une plateforme d’hébergement fait avec votre projet, pour que le déploiement ne soit plus un mystère. Ensuite, prouvez sur votre ordinateur que l’API fonctionne comme elle fonctionnera sur la plateforme. Elle tourne en mode production, avec ses paramètres tirés de l’environnement. La même collection Postman la vérifie.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 40 minutes

Ce que vous devez savoir

• Le mode développement avec fastapi dev, dans Environnement et premier point de terminaison : étape 3 : démarrer le serveur.
• Les paramètres API_KEY et SHOW_DOCS, dans Protection de base : la clé d’API et Garder la documentation exacte : décider quoi exposer en production.
• Les ports et l’adresse 127.0.0.1, dans Du navigateur au serveur : les bases : ports : quel programme.

Ce qu’il vous faut sur votre ordinateur

• L’API protégée et testée, avec journalisation, de Protection de base : exercice guidé : protéger et vérifier. python -m pytest réussit.
• requirements.txt, avec les deux groupes de paquets de Garder la documentation exacte : installer les outils de test.
• La collection dans postman. Vous l’avez exportée de nouveau à l’étape 8 de Protection de base : exercice guidé : protéger et vérifier.
• L’interface en ligne de commande Postman, de Tests et exécutions reproductibles : exécuter depuis le terminal : Postman CLI.
• .gitignore dans le projet, de Environnement et premier point de terminaison : les fichiers qui restent sur votre ordinateur.
• Pour la tâche « À vous de jouer » : un téléphone ou un deuxième appareil sur le même réseau Wi-Fi.
• Si votre projet manque ou ne fonctionne plus, copiez l’instantané end-of-m06, le projet à la fin du module 6. Utiliser un instantané présente les étapes.

Testé avec Python 3.14.6, FastAPI 0.142.2 et l’interface en ligne de commande Postman 1.69.0 sur macOS.

Ce que fait une plateforme d’hébergement

Jusqu’ici, votre API fonctionnait sur votre ordinateur, pour vous. Pour que d’autres programmes l’utilisent, elle doit fonctionner sur un ordinateur toujours allumé, avec une adresse HTTPS publique. Vous pouvez louer un serveur et tout configurer vous-même : système d’exploitation, Python, certificats HTTPS et redémarrages après une panne. Ou vous utilisez l’hébergement géré d’applications : vous donnez votre code et vos paramètres à la plateforme. Elle s’occupe du reste.

Chaque plateforme gérée fait les cinq mêmes choses, sous des noms différents :

Étape	Ce que fait la plateforme	Ce qu’elle attend de vous
Construire	Copie votre code, installe Python et vos dépendances	Une liste de dépendances et la version de Python
Démarrer	Exécute votre application avec une commande de démarrage	La commande, ou un paramètre qui indique quelle application exécuter
Écouter	Envoie les requêtes d’Internet à votre application, sur un port	Une application qui écoute sur la bonne adresse et le bon port
Configurer	Fournit à votre application ses variables d’environnement	Les paramètres et les secrets, saisis sur la plateforme, pas dans le code
Maintenir en marche	Gère HTTPS, les redémarrages après une panne et les journaux (logs)	Un point de terminaison de santé et des journaux utiles

Vous n’avez pas besoin de Docker pour cela. Docker décrit ces mêmes étapes d’une autre façon, qu’un cours ultérieur enseigne.

Mode développement et mode production

fastapi dev sert sur votre ordinateur. Une plateforme exécute plutôt fastapi run :

	fastapi dev	fastapi run
Redémarre quand un fichier change	Oui	Non. Le code de production ne change pas pendant son exécution.
Écoute sur	127.0.0.1 : seul votre ordinateur peut se connecter	0.0.0.0 : tous les réseaux de l’ordinateur
Sert à	Écrire du code	Servir les clients

127.0.0.1 accepte seulement les connexions provenant du même ordinateur. Sur un serveur, les requêtes viennent d’autres ordinateurs. L’application doit donc écouter sur 0.0.0.0, qui signifie « sur toutes les adresses réseau de cet ordinateur ». Une application qui écoute sur 127.0.0.1 sur un serveur fonctionne, mais personne ne peut l’atteindre.

Plusieurs plateformes choisissent aussi le port pour vous et le fournissent à l’application dans une variable d’environnement, souvent appelée PORT. FastAPI Cloud, que vous utilisez dans la prochaine leçon, démarre l’application lui-même. Vous n’avez donc pas à gérer PORT sur cette plateforme. Sur d’autres plateformes, la commande de démarrage est souvent fastapi run --port $PORT.

Exemple détaillé : décrire le projet pour une plateforme

Une plateforme doit connaître les dépendances, la version de Python et l’application à exécuter. L’emplacement standard pour ces trois éléments est un fichier nommé pyproject.toml, dans le dossier du projet :

pyproject.toml

[project]
name = "ticket-api"
version = "1.0.0"
description = "Classifies support tickets into a category and a priority."
requires-python = ">=3.12"
dependencies = ["fastapi[standard]==0.142.2"]

[tool.fastapi]
entrypoint = "ticket_api.main:app"

[tool.pytest.ini_options]
testpaths = ["tests"]

Section	Signification
[project]	Le nom du projet, sa version, les versions de Python prises en charge et les paquets nécessaires à son exécution.
dependencies	Seulement ce dont le serveur a besoin. pytest et httpx2 servent à travailler sur le projet et restent donc dans requirements.txt.
[tool.fastapi] entrypoint	Indique à la commande fastapi quelle application exécuter : l’objet app dans le module ticket_api.main.
[tool.pytest.ini_options]	pytest cherche les tests seulement dans tests.

Avec le point d’entrée dans le fichier, les commandes deviennent plus courtes, même sur votre ordinateur :

Terminal

fastapi dev

Sortie (premières lignes)

 ⚡️ Starting FastAPI in development mode

 🐍 Using import string: ticket_api.main:app

Remarque

La plateforme installe les paquets à partir de pyproject.toml. Le serveur reçoit donc les versions compatibles les plus récentes des dépendances de FastAPI. Votre requirements-lock.txt ne lui parvient pas. Pour verrouiller aussi chaque version sur le serveur, il faut un fichier de verrouillage que la plateforme lit, comme uv.lock. Pour ce cours, la seule version fixée de FastAPI suffit.

Exemple détaillé : le mode production sur votre ordinateur

Amira exécute l’API comme le serveur le fera, avec les paramètres de production tirés de l’environnement :

macOS

API_KEY=local-dev-key SHOW_DOCS=false fastapi run

Windows

$env:API_KEY = "local-dev-key"
$env:SHOW_DOCS = "false"
fastapi run

Linux

API_KEY=local-dev-key SHOW_DOCS=false fastapi run

Sortie

 ⚡️ Starting FastAPI in production mode

 🐍 Using import string: ticket_api.main:app

 🌐 Server started at http://0.0.0.0:8000
    Documentation at http://0.0.0.0:8000/docs

  Logs:

INFO:     Started server process [55799]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

L’API écoute sur 0.0.0.0. La ligne sur la documentation est le texte par défaut de la commande fastapi. Avec SHOW_DOCS=false, /docs renvoie 404. /health fonctionne. Ensuite, elle exécute la collection Postman contre cette API, avec la clé dans la commande :

Second terminal

postman collection run postman/ticket-api.postman_collection.json -e postman/local.postman_environment.json --env-var "apiKey=local-dev-key"

Toutes les requêtes et tous les tests réussissent. C’est le même code, dans le même mode, avec le même mécanisme de paramètres que sur le serveur. Cette exécution constitue aussi la simulation locale du déploiement. Si vous ne pouvez pas utiliser de plateforme d’hébergement, elle prouve que votre API est prête à être déployée.

Le chemin vers la production : le code et les secrets voyagent séparément, et trois vérifications prouvent que le résultat fonctionne.

Description textuelle du diagramme

Depuis votre ordinateur, deux éléments vont vers FastAPI Cloud par des chemins distincts. Le dossier du projet part avec fastapi deploy. La plateforme construit l’application, installe les paquets à partir de pyproject.toml, puis l’exécute avec fastapi run sur une URL HTTPS. La nouvelle clé d’API part avec fastapi cloud env set --secret. Elle devient la variable d’environnement API_KEY, à côté de SHOW_DOCS, et l’application en marche les lit. L’application écrit des journaux, une ligne par requête avec son identifiant. Trois vérifications prouvent qu’elle fonctionne : /health (le processus fonctionne), /ready (il peut classifier) et la collection Postman avec l’environnement Deployed (déployé).

Exercice guidé : prêt pour l’hébergement

1. Créez pyproject.toml comme dans l’exemple détaillé.
2. Arrêtez le serveur de développement et redémarrez-le avec seulement fastapi dev. Il trouve l’application grâce au point d’entrée.
3. Arrêtez-le et démarrez l’API en mode production avec API_KEY=local-dev-key SHOW_DOCS=false fastapi run. Vérifiez qu’elle écoute sur 0.0.0.0:8000.
4. Appelez /health (200) et /docs (404).
5. Exécutez la collection Postman depuis un deuxième terminal, avec --env-var "apiKey=local-dev-key". Tous les tests réussissent.
6. Exécutez python -m pytest. Tous les tests réussissent. (Les tests créent leur propre application avec leurs propres paramètres. Les variables d’environnement du serveur en marche ne les affectent donc pas.)
7. Arrêtez le serveur. Vérifiez que .gitignore contient .venv/, __pycache__/, .env et .fastapicloud/, comme dans Environnement et premier point de terminaison : les fichiers qui restent sur votre ordinateur. Si une ligne manque, ajoutez-la. La commande de déploiement de la prochaine leçon exclut les fichiers que .gitignore contient. (.fastapicloud/ sera créé dans la prochaine leçon et relie seulement votre dossier à votre propre application.)

À vous de jouer : depuis un autre appareil

Trouvez l’adresse de votre ordinateur sur votre réseau domestique (sur macOS : ipconfig getifaddr en0; sur Windows : ipconfig, l’adresse IPv4; sur Linux : hostname -I). Démarrez l’API avec fastapi run et ouvrez http://<that address>:8000/health sur votre téléphone, sur le même réseau Wi-Fi. Essayez ensuite la même chose avec fastapi dev. Qu’est-ce qui change, et pourquoi?

Afficher la réponse

Avec fastapi run, le téléphone reçoit {"status":"ok"} : l’application écoute sur 0.0.0.0 et accepte donc les connexions du réseau. Avec fastapi dev, le téléphone ne peut pas se connecter. L’application écoute seulement sur 127.0.0.1, qui désigne uniquement cet ordinateur. C’est exactement la différence entre votre ordinateur et un serveur. (Si aucune des deux méthodes ne fonctionne, un pare-feu sur votre ordinateur bloque peut-être le port 8000. Ne le désactivez pas pour ce test.)

Erreur courante

Ça fonctionne sur mon ordinateur, mais pas sur le serveur

Symptôme : la plateforme indique que le déploiement a réussi, mais l’URL renvoie une erreur. Ou la plateforme indique que l’application ne répond pas, ou la redémarre sans cesse.

Cause : une des cinq étapes diffère sur le serveur. Les causes les plus courantes :

1. Une dépendance est installée sur votre ordinateur, mais absente de pyproject.toml. L’importation échoue donc sur le serveur.
2. L’application écoute sur 127.0.0.1, ou sur un port différent de celui que la plateforme attend.
3. Un paramètre existe seulement dans votre terminal. Sur le serveur, la valeur par défaut est utilisée, ou l’application s’arrête au démarrage (par exemple, un CLASSIFIER_MODE inconnu).

Solution :

1. Lisez d’abord les journaux de la plateforme. Ils montrent la sortie de la commande de démarrage, y compris la trace d’une erreur d’importation.
2. Exécutez l’application en mode production sur votre ordinateur, avec seulement les paramètres du serveur. Utilisez un nouvel environnement virtuel contenant seulement les paquets de dependencies dans pyproject.toml (python -m pip install "fastapi[standard]==0.142.2").
3. Comparez les variables d’environnement du serveur avec celles que votre application lit dans config.py.

Vérifiez votre compréhension

Pourquoi pyproject.toml contient-il seulement fastapi[standard] dans dependencies, et pas pytest et httpx2?

Afficher la réponse

dependencies contient ce dont l’application a besoin pour fonctionner, et la plateforme installe exactement cela. pytest et httpx2 servent seulement à travailler sur le code : exécuter les tests et vérifier le contrat. Les installer sur le serveur ralentirait la construction et augmenterait la taille du serveur, sans avantage. Ils restent dans requirements.txt, que vous utilisez sur votre ordinateur.

Récapitulatif

• Une plateforme gérée construit, démarre, configure et maintient votre application en marche, et lui achemine les requêtes. Elle a besoin des dépendances, d’une commande de démarrage ou d’un point d’entrée, et de paramètres.
• fastapi run est le mode production : aucun rechargement, et l’application écoute sur 0.0.0.0.
• pyproject.toml indique ce dont l’application a besoin pour fonctionner, ses versions de Python et son point d’entrée.
• L’exécution en mode production sur votre ordinateur, avec les paramètres de production et la collection Postman, constitue la simulation locale du déploiement.

Ensuite, vous déployez l’API sur Internet, avec ses secrets hors du code.

Leçon suivante : Publier en toute sécurité