tva
← Insights

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:

  1. Sviluppo locale: Costruisci e testa la tua app React con npm run dev
  2. Build di produzione: Crea file statici ottimizzati con npm run build
  3. Containerizzazione: Impacchetta i file di build in un container Docker nginx
  4. Deploy sul server: Carica e avvia il container sul server di produzione
  5. Registrazione Traefik: Routing automatico e provisioning del certificato SSL
  6. 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 ingresso
  • assets/ – 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.com all'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:

  1. DNS non punta correttamente al server
  2. Porte 80/443 non accessibili da internet
  3. 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:

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.