Deploy di applicazioni React in produzione: configurazione completa con Docker e reverse proxy Traefik
Costruire un'applicazione React in locale è semplice. Fare il deploy correttamente sui server di produzione? È qui che la maggior parte degli sviluppatori incontra ostacoli inaspettati. Questa guida documenta una sessione di debugging reale di un deployment in cui tutto sembrava configurato correttamente – container in esecuzione, label Traefik impostate, DNS risolto – eppure l'applicazione restituiva errori 404 persistenti.
Oggi, vi guideremo attraverso il processo completo di build delle applicazioni React in locale e deploy su server Docker di produzione con corretta configurazione del reverse proxy, SSL automatico e routing professionale dei domini. Questo approccio si basa sulla nostra filosofia di soluzioni self-hosted – in modo simile a come abbiamo mostrato che è possibile fare il self-hosting di n8n per l'automazione dei workflow e costruire stack di sviluppo multi-tenant per un controllo operativo completo.
Il problema con i deployment React tradizionali
La maggior parte dei tutorial sul deployment React salta i dettagli critici per la produzione. Troverai guide che mostrano npm run build e la copia dei file su nginx, ma raramente coprono:
Conflitti di configurazione:
- Router HTTP personalizzati che sovrascrivono i redirect globali
- Errori di sintassi nelle label Traefik che causano fallimenti silenziosi
- Problemi di binding IPv6 vs IPv4 negli health check
- Mappature delle porte di servizio mancanti che producono errori 404
Gestione delle risorse:
- Errori di disco pieno che impediscono la registrazione dei container
- Immagini Docker sovradimensionate a causa di artefatti di build non necessari
- Strategie di caching inefficienti che rallentano i deployment
- Vincoli di memoria che influenzano le prestazioni di build
Prontezza per la produzione:
- Automazione corretta dei certificati SSL
- Strategie di deployment a zero downtime
- Configurazioni degli health check
- Integrazione di logging e monitoraggio
Il risultato? Ore sprecate a fare il debug del perché un'app perfettamente funzionante in locale restituisce misteriosi errori 404 in produzione, anche se “tutto sembra corretto.”
Gli strumenti che utilizziamo
Vediamo cosa fa ciascun componente nella nostra architettura snella di deployment React:
Vite: strumento di build moderno
Vite offre sviluppo rapidissimo e build di produzione ottimizzate. A differenza di Create React App, Vite sfrutta i moduli ES nativi durante lo sviluppo e crea bundle altamente ottimizzati per la produzione. La tua app React viene compilata in secondi aniché minuti.
Il vantaggio chiave? Vite gestisce automaticamente il code splitting, il tree shaking e l'ottimizzazione delle risorse. Ottieni build production-ready senza configurazioni webpack complesse.
Docker: containerizzazione per la coerenza
Docker garantisce che la tua app React funzioni in modo identico in sviluppo e produzione. Lo stesso container nginx che serve la tua app in locale si comporterà esattamente allo stesso modo sul server di produzione – eliminando il classico problema “funziona sulla mia macchina”.
Pensa a Docker come al confezionamento dell'intero ambiente applicativo (file di build React, configurazione nginx e runtime) in un container portatile che funziona ovunque.
Traefik: reverse proxy intelligente
Traefik agisce come un direttore del traffico intelligente, instradando automaticamente le richieste alle applicazioni containerizzate corrette in base ai nomi di dominio. Invece di configurare manualmente regole nginx o Apache complesse per ogni nuova applicazione, Traefik legge le label dai tuoi container Docker e configura il routing automaticamente.
Nella nostra configurazione Docker multi-tenant, abbiamo dimostrato la potenza di Traefik per la gestione di molteplici ambienti client. Gli stessi principi si applicano qui per la gestione di più applicazioni React su un singolo server.
Il bello è che Traefik gestisce la terminazione SSL tramite Let's Encrypt automaticamente, offre service discovery automatico e fornisce monitoraggio dettagliato – il tutto con una configurazione minima.
nginx: server web di produzione
nginx serve i tuoi file statici di build React con prestazioni eccezionali. È lo standard de facto per servire contenuti statici in produzione, gestendo migliaia di connessioni concorrenti in modo efficiente utilizzando risorse minime.
Comprendere il flusso di deployment
Ecco il percorso completo dallo sviluppo locale alla produzione:
- Sviluppo locale: Costruisci e testa la tua app React con
npm run dev - Build di produzione: Crea file statici ottimizzati con
npm run build - Containerizzazione: Impacchetta i file di build in un container Docker nginx
- Deploy sul server: Carica e avvia il container sul server di produzione
- Registrazione Traefik: Routing automatico e provisioning del certificato SSL
- Monitoraggio della salute: Health check continui per garantire la disponibilità
Ciò che rende questo approccio potente è l'automazione. Una volta configurato correttamente, puoi fare il deploy degli aggiornamenti in meno di 60 secondi con un singolo comando.
Configurazione dell'applicazione React
Struttura del progetto per la produzione
Organizza il tuo progetto React pensando al deployment:
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
Ottimizzazione della configurazione Vite
Crea vite.config.ts con impostazioni ottimizzate per la produzione:
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
},
})
Questa configurazione:
- Separa le librerie vendor per un migliore caching
- Minifica il codice per file di dimensioni ridotte
- Disabilita le source map in produzione (previene l'esposizione del codice)
- Ottimizza lo splitting dei chunk per tempi di caricamento più rapidi
Build per la produzione
Crea il tuo bundle di produzione ottimizzato:
# Install dependencies
npm install
# Create production build
npm run build
# Verify build output
ls -lh dist/
La tua cartella dist/ dovrebbe contenere:
index.html– Punto di ingressoassets/– JS, CSS e immagini minificati- File statici da
public/
Creazione del container di produzione
Configurazione nginx per React
Le applicazioni React utilizzano il routing lato client, richiedendo una configurazione nginx speciale. Crea 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'elemento fondamentale è try_files $uri $uri/ /index.html che assicura che React Router funzioni correttamente in produzione – tutte le rotte vengono servite con il file principale index.html.
Dockerfile per la produzione
Crea un Dockerfile ottimizzato:
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;"]
Questo utilizza nginx:alpine per un'immagine di produzione minimale (solo ~8MB) che contiene tutto il necessario per servire la tua app React.
Configurazione Docker Compose
Crea docker-compose.yml per un deployment semplice:
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
Note critiche sulla configurazione:
La sezione labels è dove molti deployment falliscono. Nota cosa NON includiamo:
- Nessuna definizione separata del router HTTP
- Nessun middleware di redirect personalizzato
- Nessuna configurazione dell'entrypoint HTTP
Perché? Perché la configurazione globale di Traefik gestisce già i redirect HTTP→HTTPS. Aggiungere router HTTP personalizzati sovrascrive questo comportamento e causa errori 404 – esattamente il problema che abbiamo risolto nella nostra sessione di debugging.
Deploy sul server di produzione
Prerequisiti sul server
Il tuo server di produzione necessita di:
Ambiente 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
Se Traefik non è configurato, fai riferimento alla nostra guida Docker multi-tenant che copre la configurazione completa di Traefik.
Spazio disco sufficiente:
# Check available space
df -h /
# You need at least 2-5GB free for Docker operations
Configurazione DNS:
- Punta
app.yourdomain.comall'indirizzo IP del tuo server - Attendi la propagazione DNS (di solito 5-60 minuti)
Caricamento dell'applicazione
Trasferisci la tua applicazione sul server:
# 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/
Build e avvio del container
Collegati via SSH al tuo server e fai il deploy:
# 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
Verifica del deployment
Controlla che tutto funzioni:
# 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
Dovresti vedere HTTP/2 200 dal comando curl, indicando il successo.
Errori di deployment comuni e soluzioni
Errore 404 nonostante la configurazione corretta
Sintomo: Traefik restituisce HTTP/2 404 anche se il container funziona internamente.
Causa principale: Definizioni multiple di router per lo stesso servizio senza corretta mappatura delle porte, o router HTTP personalizzati che sovrascrivono i redirect globali di Traefik.
Soluzione:
# 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"
Il redirect globale HTTP→HTTPS di Traefik (configurato in traefik.yml) gestisce automaticamente il traffico HTTP. I router HTTP personalizzati per singolo servizio creano conflitti.
Container in stato unhealthy
Sintomo: docker compose ps mostra il container come “unhealthy”
Causa principale: Health check che utilizza localhost che si risolve in IPv6 [::1], ma nginx ascolta solo su IPv4.
Soluzione:
healthcheck:
# Use explicit IPv4 address instead of localhost
test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:80/health"]
Build Docker fallisce con “No Space Left”
Sintomo: La build fallisce con errori di spazio disco
Soluzione:
# 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
Se il disco è veramente pieno (>95%), devi liberare spazio o espandere lo storage. Le operazioni Docker richiedono spazio temporaneo per il caching dei layer e la build.
Il certificato SSL non viene generato
Sintomo: Curl mostra un certificato auto-firmato dopo più di 10 minuti
Cause comuni:
- DNS non punta correttamente al server
- Porte 80/443 non accessibili da internet
- Raggiunto il limite di Let’s Encrypt (5 per dominio a settimana)
Soluzione:
# 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
Errori 404 di React Router al refresh
Sintomo: L'app funziona al caricamento iniziale ma mostra 404 quando si fa refresh su rotte come /about
Causa principale: Direttiva try_files mancante nella configurazione nginx
Soluzione: Assicurati che il tuo nginx.conf includa:
location / {
try_files $uri $uri/ /index.html;
}
Questo indica a nginx di servire index.html per tutte le rotte, lasciando a React Router la gestione del routing lato client.
Il container si avvia ma Traefik non riesce a raggiungerlo
Sintomo: Il container è in esecuzione ma Traefik restituisce “Service Unavailable”
Soluzione:
# 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
Ottimizzazione per la produzione
Implementazione di deployment a zero downtime
Aggiorna la tua applicazione senza interruzioni:
#!/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 check avanzati
Implementa un monitoraggio completo della salute:
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
Questo controlla sia l'endpoint di salute SIA la rotta principale dell'applicazione, assicurando che l'intera app risponda correttamente.
Ottimizzazione delle prestazioni
Affina nginx per migliori prestazioni:
# 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;
}
Limiti delle risorse
Previeni l'esaurimento delle risorse con limiti ai container:
services:
my-react-app:
# ... existing config ...
deploy:
resources:
limits:
cpus: '0.5'
memory: 512M
reservations:
cpus: '0.25'
memory: 256M
nginx che serve file statici React richiede risorse minime – 512MB di memoria e mezzo core CPU gestiscono migliaia di utenti concorrenti.
Perché i deployment Docker self-hosted sono importanti
Il self-hosting delle tue applicazioni React su infrastruttura Docker ti offre il controllo completo sulla pipeline di deployment senza vendor lock-in. Puoi fare il deploy di applicazioni illimitate sulla tua infrastruttura, personalizzare ogni aspetto del processo di deployment e integrarti senza problemi con i tuoi servizi self-hosted esistenti.
Questo approccio funziona particolarmente bene se combinato con la nostra architettura Docker multi-tenant, dove puoi ospitare più applicazioni client sulla stessa infrastruttura con completo isolamento.
Automazione e integrazione CI/CD
Deployment con GitHub Actions
Automatizza i deployment ad ogni 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
Per gli utenti 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
Monitoraggio del deployment in produzione
Strategia di logging
Implementa un logging completo:
# Add to docker-compose.yml
services:
my-react-app:
# ... existing config ...
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
Visualizza i log in modo efficiente:
# 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
Metriche e avvisi
Monitora la salute dei container:
#!/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\":\"Container $CONTAINER is $STATUS\"}"
fi
Esegui questo tramite cron ogni 5 minuti per un monitoraggio di base.
Collegamento di React all'infrastruttura backend
La tua app React probabilmente deve comunicare con servizi backend. Questo si integra naturalmente con l'infrastruttura self-hosted. Se stai eseguendo n8n per l'automazione dei workflow o Windmill per i workflow backend, configura CORS e routing API appropriati nella tua configurazione 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;
}
Questo funziona senza problemi quando tutti i servizi fanno parte della stessa rete Docker, come dimostrato nella nostra guida all'architettura multi-tenant.
Build specifiche per ambiente
Ambienti diversi spesso necessitano di configurazioni diverse:
// 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',
},
}))
Build per ambienti diversi:
# Development build
npm run build -- --mode development
# Staging build
npm run build -- --mode staging
# Production build
npm run build -- --mode production
Il vero valore della comprensione di questa configurazione
Questo approccio al deployment è importante se:
Gestisci più applicazioni:
- Fai il deploy di app React insieme a servizi backend sulla stessa infrastruttura
- Usi processi di deployment coerenti su tutti i progetti
- Ti integri con strumenti self-hosted come n8n e Windmill
Costruisci per i clienti:
- Domini personalizzati professionali protetti da SSL
- Controllo completo sull'infrastruttura e sui deployment
- Nessuna limitazione della piattaforma o vendor lock-in
Impari l'infrastruttura:
- Comprendi i fondamentali della containerizzazione Docker
- Padroneggi la configurazione del reverse proxy Traefik
- Fai il debug sistematico dei problemi di deployment in produzione
La configurazione documentata qui si basa su una sessione di debugging reale – i problemi descritti sono realmente accaduti e le soluzioni hanno effettivamente funzionato. Questo la rende più preziosa dei tutorial teorici perché stai vedendo le insidie reali e come evitarle.
Se combinata con la nostra architettura Docker multi-tenant, questa forma una base per la distribuzione di applicazioni scalabili e self-hosted che controlli completamente.
Risorse correlate
Per ulteriori guide sull'infrastruttura self-hosted, consulta queste risorse:
- Self-hosting di n8n per l'automazione dei workflow – Automatizza deployment e task infrastrutturali
- Self-hosting di Windmill con Docker – Piattaforma alternativa di automazione dei workflow
- Costruire stack Docker multi-tenant – Configurazione completa di Traefik per più applicazioni
- tva Duplicate Pro – Strumenti di automazione WordPress per workflow di contenuti
Queste guide dimostrano diversi aspetti della costruzione di infrastruttura self-hosted che ti offre il controllo completo mantenendo standard professionali.
Supporto professionale
La configurazione di deployment React di livello produttivo coinvolge molte considerazioni infrastrutturali. Sebbene abbiamo fornito documentazione completa, ogni progetto ha requisiti unici, vincoli infrastrutturali esistenti e esigenze di prestazioni specifiche.
Se stai implementando un'infrastruttura di deployment React per l'uso in produzione o hai bisogno di personalizzazione per le tue specifiche esigenze di distribuzione ai clienti, possiamo aiutarti con:
- Pipeline di deployment personalizzate su misura per il tuo workflow
- Integrazione con sistemi CI/CD esistenti
- Ottimizzazione delle prestazioni per applicazioni ad alto traffico
- Strategie di deployment multi-regione
- Formazione del team sulle best practice di Docker e Traefik
- Gestione continua dell'infrastruttura e monitoraggio
Contattaci tramite tva.sg/contact per discutere le tue esigenze di deployment React e ricevere una guida professionale sull'implementazione.
Che tu stia scalando un'agenzia esistente, lanciando un nuovo prodotto SaaS o costruendo capacità di distribuzione ai clienti di livello enterprise, siamo qui per aiutarti a avere successo con deployment React self-hosted e containerizzati che mantengono la tua indipendenza offrendo risultati professionali.