infra / nginx

Installation et structure de configuration

Leçon 21 exercice

Explication

Ce que vous allez apprendre

Installer Nginx sur les principales familles de distributions Linux
Comprendre le rôle de chaque fichier et dossier de l'arborescence /etc/nginx/
Distinguer sites-available (catalogue) de sites-enabled (ce qui est réellement actif)
Prendre le réflexe systématique de tester une configuration avant de la recharger
Choisir entre reload (sans coupure) et restart (avec coupure) selon la situation

Dans quel contexte ?

Un administrateur système vient de provisionner un nouveau serveur Ubuntu et doit y installer Nginx pour héberger le premier site du client. Avant même d'écrire une seule ligne de configuration de site, il doit comprendre comment Nginx organise ses fichiers : où écrire une nouvelle configuration, comment l'activer, et surtout comment vérifier qu'elle est valide avant de risquer une coupure de service en production.

D'abord, l'installation elle-même est la partie la plus simple

Sur Debian/Ubuntu, apt install nginx suffit ; sur RHEL/Fedora/Rocky, c'est dnf install nginx. Une fois installé, systemctl enable nginx garantit que le service redémarre automatiquement après un reboot du serveur, un réglage qu'on oublie facilement mais qui évite bien des pannes après une maintenance.

Une fois Nginx installé, il faut comprendre où vivent ses fichiers

Le fichier nginx.conf est le point d'entrée, mais il ne contient presque jamais toute la configuration réelle : il se contente d'inclure d'autres fichiers via include. C'est une architecture éclatée volontairement, pour que chaque site ou chaque bloc de configuration reste dans son propre fichier, plus facile à gérer qu'un unique fichier géant.

Fichier / dossier	Rôle
`/etc/nginx/nginx.conf`	Fichier principal, définit le contexte global et inclut le reste
`/etc/nginx/conf.d/*.conf`	Configurations globales additionnelles, toutes chargées automatiquement
`/etc/nginx/sites-available/`	Catalogue de configurations de sites, actives ou non
`/etc/nginx/sites-enabled/`	Symlinks vers `sites-available` : seuls les fichiers présents ici sont actifs

Ensuite, un mécanisme malin mais parfois déroutant au premier abord : les symlinks

Un site écrit dans sites-available/example.com.conf n'est pas actif tant qu'aucun lien symbolique ne pointe vers lui depuis sites-enabled/. Ce système à deux dossiers permet de désactiver temporairement un site (en supprimant juste le lien) sans perdre sa configuration (le fichier source reste intact dans sites-available).

Prérequis

Il faut être à l'aise avec les liens symboliques Linux (ln -s) et les permissions de base : ce sont des notions transversales, pas spécifiques à Nginx, qui reviendront régulièrement dans ce cours.

Il reste une règle absolue avant tout changement de configuration

nginx -t valide la syntaxe de l'ensemble des fichiers inclus, sans rien appliquer. Cette commande doit devenir un réflexe automatique avant chaque modification : une erreur de syntaxe non détectée avant un reload peut, selon les cas, empêcher Nginx de redémarrer correctement et provoquer une coupure de service totalement évitable.

Bonne pratique

Prends l'habitude systématique d'enchaîner sudo nginx -t && sudo systemctl reload nginx plutôt que d'exécuter les deux commandes séparément : le && garantit que le reload n'a lieu que si le test de syntaxe a réussi, éliminant tout risque d'appliquer une configuration cassée.

Piège fréquent

Confondre reload et restart peut couper des connexions actives sans raison : reload recharge la configuration en douceur, sans interrompre les requêtes en cours, alors que restart arrête puis relance tout le processus, coupant net toutes les connexions ouvertes. En production, reload doit être le choix par défaut.

Maintenant que tu sais où et comment écrire une configuration, la prochaine leçon aborde le cœur du sujet : comment Nginx choisit quel site et quelle route servir pour une requête donnée, avec les server blocks et les location.

Commandes & code

Installation et structure de configuration

# --- Debian / Ubuntu ---
sudo apt update
sudo apt install nginx -y
sudo systemctl status nginx          # doit afficher "active (running)"
sudo systemctl enable nginx          # démarrage automatique au boot

# --- RHEL / CentOS / Rocky ---
sudo dnf install nginx -y
sudo systemctl enable --now nginx

# --- Windows (via choco, pour du dev local) ---
choco install nginx

# Vérifier la version et les modules compilés
nginx -v
nginx -V                              # -V majuscule = détails de compilation (modules inclus)

# Arborescence standard (Debian/Ubuntu)
/etc/nginx/
├── nginx.conf                # fichier de config principal (le "chef d'orchestre")
├── mime.types                 # associations extension -> Content-Type
├── conf.d/                     # configs globales additionnelles (*.conf, tout est inclus)
├── sites-available/              # configs de sites écrites ici (pas actives par défaut)
│   └── example.com.conf
└── sites-enabled/                   # symlinks vers sites-available -> RENDS le site actif
    └── example.com.conf -> ../sites-available/example.com.conf

# /etc/nginx/nginx.conf (structure de base, contexte "main")
user www-data;                         # utilisateur qui exécute les workers (pas root !)
worker_processes auto;                 # 1 worker par coeur CPU, ajusté plus tard (leçon perf)
pid /run/nginx.pid;

events {
    worker_connections 1024;           # connexions simultanées max par worker
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    include /etc/nginx/conf.d/*.conf;          # charge les configs globales
    include /etc/nginx/sites-enabled/*.conf;   # charge les sites activés
}

# Activer un site (créer le symlink sites-available -> sites-enabled)
sudo ln -s /etc/nginx/sites-available/example.com.conf /etc/nginx/sites-enabled/

# Désactiver un site (supprime juste le symlink, garde le fichier source)
sudo rm /etc/nginx/sites-enabled/example.com.conf

# Toujours tester AVANT de recharger : erreur de syntaxe = downtime évitable
sudo nginx -t
# syntax is ok
# test is successful

sudo systemctl reload nginx    # recharge la config SANS couper les connexions en cours
sudo systemctl restart nginx   # redémarre complètement (coupe les connexions)

Résumé

nginx.conf inclut conf.d/*.conf et sites-enabled/*.conf : la vraie config est éclatée en plusieurs fichiers.
sites-available/ = catalogue de configs ; sites-enabled/ = symlinks vers ce qui est réellement actif.
nginx -t valide la syntaxe avant tout reload : à faire systématiquement, sans exception.
reload (sans coupure) est préférable à restart (coupe les connexions actives) en production.

Exercices pratiques

1 disponible

Mission : activer un nouveau site sans provoquer de coupure

Objectif : Diagnostiquer pourquoi un site fraîchement configuré ne répond pas, puis l'activer et le recharger sans couper le service existant.

Contexte

Un collègue a écrit /etc/nginx/sites-available/shop.example.com.conf pour un nouveau site, a redémarré le serveur avec sudo systemctl restart nginx, et se plaint que (1) le nouveau site renvoie toujours une erreur de connexion, et (2) tous les visiteurs du site existant ont été brièvement déconnectés pendant l'opération. Diagnostique les deux problèmes.

Résoudre l’exercice →