Déployer des applications React en production : configuration Docker complète avec le reverse proxy Traefik
Construire une application React en local est simple. La déployer correctement sur des serveurs de production ? C'est là que la plupart des développeurs se heurtent à des obstacles inattendus. Ce guide documente une véritable session de débogage de déploiement où tout semblait correctement configuré — conteneur en fonctionnement, labels Traefik définis, DNS résolu — et pourtant l'application renvoyait des erreurs 404 persistantes.
Aujourd'hui, nous allons parcourir le processus complet de construction d'applications React en local et de leur déploiement sur des serveurs Docker de production avec une configuration appropriée du reverse proxy, un SSL automatique et un routage de domaine professionnel. Cette approche s'appuie sur notre philosophie de solutions auto-hébergées — de manière similaire à ce que nous avons montré pour l'auto-hébergement de n8n pour l'automatisation des workflows et la construction de piles de développement multi-locataires pour un contrôle opérationnel complet.
Le problème des déploiements React traditionnels
La plupart des tutoriels de déploiement React passent sous silence les détails critiques de production. Vous trouverez des guides montrant npm run build et la copie des fichiers vers nginx, mais ils couvrent rarement :
Conflits de configuration :
- Des routeurs HTTP personnalisés qui remplacent les redirections globales
- Des erreurs de syntaxe dans les labels Traefik qui causent des échecs silencieux
- Des problèmes de liaison IPv6 vs IPv4 dans les health checks
- Des mappages de ports de service manquants qui produisent des erreurs 404
Gestion des ressources :
- Des erreurs de disque plein empêchant l'enregistrement des conteneurs
- Le gonflement des images Docker à cause d'artéfacts de build inutiles
- Des stratégies de mise en cache inefficaces qui ralentissent les déploiements
- Des contraintes de mémoire affectant les performances de build
Prêt pour la production :
- Automatisation correcte des certificats SSL
- Stratégies de déploiement sans interruption
- Configurations des health checks
- Intégration de la journalisation et de la surveillance
Le résultat ? Des heures perdues à déboguer pourquoi une application fonctionnant parfaitement en local renvoie de mystérieuses erreurs 404 en production, alors que « tout semble correct ».
Les outils que nous utilisons
Comprenons le rôle de chaque composant dans notre architecture de déploiement React rationalisée :
Vite : outil de build moderne
Vite offre un développement ultra-rapide et des builds de production optimisés. Contrairement à Create React App, Vite exploite les modules ES natifs pendant le développement et produit des bundles hautement optimisés pour la production. Votre application React se compile en quelques secondes au lieu de minutes.
L'avantage principal ? Vite gère automatiquement le découpage du code, le tree shaking et l'optimisation des ressources. Vous obtenez des builds prêts pour la production sans configurations webpack complexes.
Docker : la conteneurisation pour la cohérence
Docker garantit que votre application React fonctionne de manière identique en développement et en production. Le même conteneur nginx servant votre application localement se comportera exactement de la même façon sur votre serveur de production — éliminant le classique problème « ça marche sur ma machine ».
Considérez Docker comme un emballage de l'ensemble de votre environnement applicatif (fichiers de build React, configuration nginx et runtime) dans un conteneur portable qui fonctionne partout.
Traefik : reverse proxy intelligent
Traefik agit comme un aiguilleur de trafic intelligent, routant automatiquement les requêtes vers les applications conteneurisées appropriées en fonction des noms de domaine. Au lieu de configurer manuellement des règles nginx ou Apache complexes pour chaque nouvelle application, Traefik lit les labels de vos conteneurs Docker et configure le routage automatiquement.
Dans notre configuration Docker multi-locataire, nous avons démontré la puissance de Traefik pour gérer plusieurs environnements clients. Les mêmes principes s'appliquent ici pour gérer plusieurs applications React sur un seul serveur.
L'avantage est que Traefik gère la terminaison SSL via Let's Encrypt automatiquement, offre la découverte automatique des services et propose une surveillance détaillée — le tout avec une configuration minimale.
nginx : serveur web de production
nginx sert vos fichiers statiques React avec des performances exceptionnelles. C'est le standard de facto pour servir du contenu statique en production, gérant des milliers de connexions simultanées efficacement tout en utilisant des ressources minimales.
Comprendre le flux de déploiement
Voici le parcours complet du développement local à la production :
- Développement local : construisez et testez votre application React avec
npm run dev - Build de production : créez les fichiers statiques optimisés avec
npm run build - Conteneurisation : empaquetez les fichiers de build dans un conteneur Docker nginx
- Déploiement serveur : transférez et démarrez le conteneur sur le serveur de production
- Enregistrement Traefik : routage automatique et provisionnement du certificat SSL
- Surveillance de la santé : des health checks continus assurent la disponibilité
Ce qui rend cette approche puissante, c'est l'automatisation. Une fois correctement configuré, vous pouvez déployer des mises à jour en moins de 60 secondes avec une seule commande.
Configurer votre application React
Structure du projet pour la production
Organisez votre projet React en pensant au déploiement :
my-react-app/
├── src/ # React source code
├── public/ # Static assets
├── dist/ # Build output (auto-generated)
├── package.json # Dependencies
├── vite.config.ts # Vite configuration
├── Dockerfile # Container definition
├── nginx.conf # nginx configuration
└── docker-compose.yml # Deployment definition
Optimiser votre configuration Vite
Créez vite.config.ts avec des paramètres optimisés pour la production :
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
build: {
outDir: 'dist',
sourcemap: false, // Disable in production for security
minify: 'terser',
rollupOptions: {
output: {
manualChunks: {
vendor: ['react', 'react-dom'],
},
},
},
},
server: {
port: 3000,
host: true, // Enable network access
},
})
Cette configuration :
- Sépare les bibliothèques tierces pour une meilleure mise en cache
- Minifie le code pour des fichiers plus petits
- Désactive les source maps en production (empêche l'exposition du code)
- Optimise le découpage des chunks pour des temps de chargement plus rapides
Construire pour la production
Construisez votre bundle de production optimisé :
# Install dependencies
npm install
# Create production build
npm run build
# Verify build output
ls -lh dist/
Votre dossier dist/ devrait contenir :
index.html— Point d'entréeassets/— JS, CSS et images minifiés- Fichiers statiques depuis
public/
Créer le conteneur de production
Configuration nginx pour React
Les applications React utilisent le routage côté client, nécessitant une configuration nginx spéciale. Créez nginx.conf :
server {
listen 80;
server_name _;
root /usr/share/nginx/html;
index index.html;
# Gzip compression for better performance
gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_types text/plain text/css text/xml text/javascript
application/x-javascript application/xml+rss
application/javascript application/json;
# Security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
# SPA: Route all paths to index.html for client-side routing
location / {
try_files $uri $uri/ /index.html;
}
# Cache static assets aggressively
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
# No cache for HTML to ensure updates are immediate
location ~* \.html$ {
expires -1;
add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0";
}
# Health check endpoint for monitoring
location /health {
access_log off;
return 200 "healthy\n";
add_header Content-Type text/plain;
}
}
L'élément critique est try_files $uri $uri/ /index.html qui garantit le bon fonctionnement de React Router en production — toutes les routes sont servies par le fichier principal index.html.
Dockerfile pour la production
Créez un Dockerfile optimisé :
FROM nginx:alpine
# Copy custom nginx configuration
COPY nginx.conf /etc/nginx/conf.d/default.conf
# Copy production build files
COPY dist/ /usr/share/nginx/html/
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
Cela utilise nginx:alpine pour une image de production minimale (seulement environ 8 Mo) qui contient tout le nécessaire pour servir votre application React.
Configuration Docker Compose
Créez docker-compose.yml pour un déploiement facile :
services:
my-react-app:
build:
context: .
dockerfile: Dockerfile
container_name: my-react-app
restart: unless-stopped
networks:
- proxy
labels:
# Enable Traefik
- "traefik.enable=true"
# Define routing rule
- "traefik.http.routers.myapp.rule=Host(`app.yourdomain.com`)"
- "traefik.http.routers.myapp.entrypoints=https"
- "traefik.http.routers.myapp.tls=true"
- "traefik.http.routers.myapp.tls.certresolver=letsencrypt"
# Define service port
- "traefik.http.services.myapp.loadbalancer.server.port=80"
healthcheck:
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:80/health"]
interval: 30s
timeout: 3s
retries: 3
start_period: 5s
networks:
proxy:
external: true
Notes de configuration critiques :
La section labels est l'endroit où de nombreux déploiements échouent. Notez ce que nous n'incluons PAS :
- Pas de définition séparée de routeur HTTP
- Pas de middleware de redirection personnalisé
- Pas de configuration d'entrypoint HTTP
Pourquoi ? Parce que la configuration globale de Traefik gère déjà les redirections HTTP vers HTTPS. Ajouter des routeurs HTTP personnalisés remplace ce comportement et provoque des erreurs 404 — exactement le problème que nous avons résolu lors de notre session de débogage.
Déployer sur votre serveur de production
Prérequis sur votre serveur
Votre serveur de production a besoin de :
Environnement Docker :
# Verify Docker is installed
docker --version
docker compose --version
# Verify Traefik is running
docker ps | grep traefik
# Verify proxy network exists
docker network ls | grep proxy
Si Traefik n'est pas configuré, consultez notre guide Docker multi-locataire qui couvre la configuration complète de Traefik.
Espace disque suffisant :
# Check available space
df -h /
# You need at least 2-5GB free for Docker operations
Configuration DNS :
- Pointez
app.yourdomain.comvers l'adresse IP de votre serveur - Attendez la propagation DNS (généralement 5 à 60 minutes)
Transférer votre application
Transférez votre application vers le serveur :
# From your local machine
scp -r my-react-app/ user@your-server:/opt/
# Or use rsync for efficient updates
rsync -avz --exclude 'node_modules' \
my-react-app/ user@your-server:/opt/my-react-app/
Construire et démarrer le conteneur
Connectez-vous en SSH à votre serveur et déployez :
# Navigate to application directory
cd /opt/my-react-app
# Build the Docker image
docker compose build
# Start the container
docker compose up -d
# Verify it's running
docker compose ps
Vérifier le déploiement
Vérifiez que tout fonctionne :
# Test container health internally
docker compose exec my-react-app wget -q -O- http://127.0.0.1/health
# Check Traefik routing (wait 30 seconds for SSL)
curl -I https://app.yourdomain.com
# View container logs
docker compose logs -f
Vous devriez voir HTTP/2 200 à la commande curl, indiquant le succès.
Échecs de déploiement courants et solutions
Erreur 404 malgré une configuration correcte
Symptôme : Traefik renvoie HTTP/2 404 alors que le conteneur fonctionne en interne.
Cause profonde : Plusieurs définitions de routeurs pour le même service sans mappage correct du port de service, ou des routeurs HTTP personnalisés remplaçant les redirections globales de Traefik.
Solution :
# Remove these labels if present:
# - "traefik.http.middlewares.myapp-redirect.redirectscheme.scheme=https"
# - "traefik.http.routers.myapp-http.rule=Host(`app.yourdomain.com`)"
# - "traefik.http.routers.myapp-http.entrypoints=http"
# - "traefik.http.routers.myapp-http.middlewares=myapp-redirect"
# Keep only HTTPS router:
labels:
- "traefik.enable=true"
- "traefik.http.routers.myapp.rule=Host(`app.yourdomain.com`)"
- "traefik.http.routers.myapp.entrypoints=https"
- "traefik.http.routers.myapp.tls.certresolver=letsencrypt"
- "traefik.http.services.myapp.loadbalancer.server.port=80"
La redirection globale HTTP vers HTTPS de Traefik (configurée dans traefik.yml) gère automatiquement le trafic HTTP. Les routeurs HTTP personnalisés par service créent des conflits.
Conteneur en statut « unhealthy »
Symptôme : docker compose ps affiche le conteneur comme « unhealthy »
Cause profonde : le health check utilise localhost qui résout vers IPv6 [::1], mais nginx n'écoute que sur IPv4.
Solution :
healthcheck:
# Use explicit IPv4 address instead of localhost
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:80/health"]
Le build Docker échoue avec « No Space Left »
Symptôme : le build échoue avec des erreurs d'espace disque
Solution :
# Check disk usage
df -h /
# Clean Docker system
docker system prune -a -f
# Remove unused images
docker image prune -a -f
# Remove unused volumes
docker volume prune -f
Si le disque est vraiment plein (> 95 %), vous devez libérer de l'espace ou étendre votre stockage. Les opérations Docker nécessitent un espace temporaire pour la mise en cache des couches et la construction.
Le certificat SSL ne se génère pas
Symptôme : curl affiche un certificat auto-signé après plus de 10 minutes
Causes courantes :
- DNS ne pointe pas correctement vers le serveur
- Ports 80/443 non accessibles depuis Internet
- Limites de débit Let's Encrypt atteintes (5 par domaine par semaine)
Solution :
# Verify DNS resolution
dig app.yourdomain.com
# Test port accessibility
curl -I http://app.yourdomain.com
# Check Traefik logs for ACME errors
docker logs traefik | grep -i acme
# Restart Traefik if needed
docker restart traefik
Erreurs 404 React Router lors du rafraîchissement
Symptôme : l'application fonctionne au chargement initial mais affiche une 404 lors du rafraîchissement sur des routes comme /about
Cause profonde : directive try_files manquante dans la configuration nginx
Solution : assurez-vous que votre nginx.conf inclut :
location / {
try_files $uri $uri/ /index.html;
}
Cela indique à nginx de servir index.html pour toutes les routes, laissant React Router gérer le routage côté client.
Le conteneur démarre mais Traefik ne peut pas l'atteindre
Symptôme : le conteneur fonctionne mais Traefik renvoie « Service Unavailable »
Solution :
# Verify container is on correct network
docker network inspect proxy
# Check if container is listed
docker inspect my-react-app | grep -A 20 Networks
# Ensure proxy network exists
docker network create proxy
Optimiser pour la production
Implémenter des déploiements sans interruption
Mettez à jour votre application sans interruption :
#!/bin/bash
# deploy-update.sh - Zero-downtime deployment
cd /opt/my-react-app
# Pull latest code (from git or updated files)
git pull origin main
# Build new production assets
npm install
npm run build
# Build new Docker image
docker compose build
# Start new container (old one still running)
docker compose up -d --no-deps --build my-react-app
# Traefik automatically routes to healthy container
# Old container is automatically stopped after new one is healthy
Health checks avancés
Implémentez une surveillance complète de la santé :
healthcheck:
test: |
wget --no-verbose --tries=1 --spider http://127.0.0.1:80/health &&
wget --no-verbose --tries=1 --spider http://127.0.0.1:80/
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
Cela vérifie à la fois l'endpoint de santé ET la route principale de l'application, garantissant que l'ensemble de l'application répond correctement.
Optimisation des performances
Affinez nginx pour de meilleures performances :
# Add to nginx.conf
server {
# ... existing config ...
# Increase buffer sizes for large headers
client_header_buffer_size 1k;
large_client_header_buffers 4 8k;
# Enable keep-alive connections
keepalive_timeout 65;
keepalive_requests 100;
# Optimize file serving
sendfile on;
tcp_nopush on;
tcp_nodelay on;
}
Limites de ressources
Prévenez l'épuisement des ressources avec des limites de conteneur :
services:
my-react-app:
# ... existing config ...
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
reservations:
cpus: '0.25'
memory: 256M
nginx servant des fichiers React statiques nécessite des ressources minimales — 512 Mo de mémoire et un demi-cœur CPU gèrent des milliers d'utilisateurs simultanés.
Pourquoi les déploiements Docker auto-hébergés comptent
L'auto-hébergement de vos applications React sur une infrastructure Docker vous donne un contrôle total sur votre pipeline de déploiement sans dépendance fournisseur. Vous pouvez déployer un nombre illimité d'applications sur votre propre infrastructure, personnaliser chaque aspect du processus de déploiement et intégrer de manière transparente vos services auto-hébergés existants.
Cette approche fonctionne particulièrement bien combinée à notre architecture Docker multi-locataire, où vous pouvez héberger plusieurs applications clients sur la même infrastructure avec une isolation complète.
Automatisation et intégration CI/CD
Déploiement avec GitHub Actions
Automatisez les déploiements à chaque push :
# .github/workflows/deploy.yml
name: Deploy to Production
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '18'
cache: 'npm'
- name: Build React app
run: |
npm ci
npm run build
- name: Deploy to server
uses: appleboy/scp-action@v0.1.4
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SSH_PRIVATE_KEY }}
source: "dist/,Dockerfile,nginx.conf,docker-compose.yml"
target: "/opt/my-react-app"
- name: Restart container
uses: appleboy/ssh-action@v0.1.10
with:
host: ${{ secrets.SERVER_HOST }}
username: ${{ secrets.SERVER_USER }}
key: ${{ secrets.SSH_PRIVATE_KEY }}
script: |
cd /opt/my-react-app
docker compose up -d --build
Pipeline CI/CD GitLab
Pour les utilisateurs de GitLab :
# .gitlab-ci.yml
stages:
- build
- deploy
build:
stage: build
image: node:18
script:
- npm ci
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 hour
deploy:
stage: deploy
image: alpine:latest
before_script:
- apk add --no-cache openssh-client
- eval $(ssh-agent -s)
- echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
script:
- scp -r dist/ Dockerfile nginx.conf docker-compose.yml $SERVER_USER@$SERVER_HOST:/opt/my-react-app/
- ssh $SERVER_USER@$SERVER_HOST "cd /opt/my-react-app && docker compose up -d --build"
only:
- main
Surveiller votre déploiement en production
Stratégie de journalisation
Implémentez une journalisation complète :
# Add to docker-compose.yml
services:
my-react-app:
# ... existing config ...
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
Consultez les logs efficacement :
# Real-time logs
docker compose logs -f my-react-app
# Last 100 lines
docker compose logs --tail=100 my-react-app
# Logs from specific time
docker compose logs --since=2h my-react-app
# Filter for errors only
docker compose logs my-react-app | grep -i error
Métriques et alertes
Surveillez la santé des conteneurs :
#!/bin/bash
# health-check.sh - Regular health monitoring
CONTAINER="my-react-app"
WEBHOOK_URL="your-notification-webhook"
STATUS=$(docker inspect --format='{{.State.Health.Status}}' $CONTAINER)
if [ "$STATUS" != "healthy" ]; then
curl -X POST $WEBHOOK_URL \
-H 'Content-Type: application/json' \
-d "{\"text\":\"Warning: Container $CONTAINER is $STATUS\"}"
fi
Exécutez ce script via cron toutes les 5 minutes pour une surveillance de base.
Connecter React à l'infrastructure backend
Votre application React a probablement besoin de communiquer avec des services backend. Cela s'intègre naturellement à l'infrastructure auto-hébergée. Si vous exécutez n8n pour l'automatisation des workflows ou Windmill pour les workflows backend, configurez correctement le CORS et le routage API dans votre configuration nginx :
# Add to nginx.conf for API proxying
location /api {
proxy_pass http://your-backend-service:3000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
Cela fonctionne parfaitement lorsque tous les services font partie du même réseau Docker, comme démontré dans notre guide d'architecture multi-locataire.
Builds spécifiques à l'environnement
Différents environnements nécessitent souvent des configurations différentes :
// vite.config.ts
export default defineConfig(({ mode }) => ({
plugins: [react()],
define: {
'import.meta.env.VITE_API_URL': JSON.stringify(
mode === 'production'
? 'https://api.yourdomain.com'
: 'http://localhost:3000'
),
},
build: {
outDir: 'dist',
sourcemap: mode !== 'production',
},
}))
Construisez pour différents environnements :
# Development build
npm run build -- --mode development
# Staging build
npm run build -- --mode staging
# Production build
npm run build -- --mode production
La vraie valeur de comprendre cette configuration
Cette approche de déploiement est pertinente si vous :
Gérez plusieurs applications :
- Déployez des applications React aux côtés de services backend sur la même infrastructure
- Utilisez des processus de déploiement cohérents pour tous les projets
- Intégrez avec des outils auto-hébergés comme n8n et Windmill
Construisez pour des clients :
- Domaines personnalisés professionnels sécurisés par SSL
- Contrôle total sur l'infrastructure et les déploiements
- Aucune limitation de plateforme ni dépendance fournisseur
Apprenez l'infrastructure :
- Comprenez les fondamentaux de la conteneurisation Docker
- Maîtrisez la configuration du reverse proxy Traefik
- Déboguez les problèmes de déploiement en production de manière systématique
La configuration documentée ici est basée sur une véritable session de débogage — les problèmes décrits se sont réellement produits et les solutions ont réellement fonctionné. Cela la rend plus précieuse que des tutoriels théoriques car vous voyez les vrais pièges et comment les éviter.
Combinée à notre architecture Docker multi-locataire, cette approche forme une fondation pour une livraison d'applications auto-hébergée et évolutive que vous contrôlez entièrement.
Ressources associées
Pour plus de guides d'infrastructure auto-hébergée, consultez ces ressources :
- Auto-héberger n8n pour l'automatisation des workflows — Automatisez les déploiements et les tâches d'infrastructure
- Auto-héberger Windmill avec Docker — Plateforme alternative d'automatisation des workflows
- Construire des piles Docker multi-locataires — Configuration complète de Traefik pour plusieurs applications
- tva Duplicate Pro — Outils d'automatisation WordPress pour les workflows de contenu
Ces guides illustrent différents aspects de la construction d'une infrastructure auto-hébergée qui vous donne un contrôle total tout en maintenant des standards professionnels.
Obtenez un accompagnement professionnel
La mise en place de déploiements React de niveau production implique de nombreuses considérations d'infrastructure. Bien que nous ayons fourni une documentation complète, chaque projet a des exigences uniques, des contraintes d'infrastructure existantes et des besoins de performance spécifiques.
Si vous implémentez une infrastructure de déploiement React pour un usage en production ou si vous avez besoin de personnalisation pour vos besoins spécifiques de livraison client, nous pouvons vous aider avec :
- Des pipelines de déploiement personnalisés adaptés à votre flux de travail
- L'intégration avec des systèmes CI/CD existants
- L'optimisation des performances pour les applications à fort trafic
- Des stratégies de déploiement multi-régions
- La formation des équipes aux bonnes pratiques Docker et Traefik
- La gestion et la surveillance continues de l'infrastructure
Contactez-nous via tva.sg/contact pour discuter de vos besoins de déploiement React et obtenir des conseils professionnels sur l'implémentation.
Que vous développiez une agence existante, lanciez un nouveau produit SaaS ou construisiez des capacités de livraison client de niveau entreprise, nous sommes là pour vous aider à réussir avec des déploiements React conteneurisés et auto-hébergés qui préservent votre indépendance tout en livrant des résultats professionnels.