tva
← Insights

Implantando Aplicações React em Produção: Configuração Completa com Docker e Proxy Reverso Traefik

Construir uma aplicação React localmente é simples. Implantá-la em servidores de produção corretamente? É aí que a maioria dos desenvolvedores encontra obstáculos inesperados. Este guia documenta uma sessão real de depuração de implantação onde tudo parecia configurado corretamente — container rodando, labels do Traefik definidas, DNS resolvendo — mas a aplicação retornava erros 404 persistentes.

Hoje, vamos percorrer o processo completo de construção de aplicações React localmente e implantação em servidores Docker de produção com configuração adequada de proxy reverso, SSL automático e roteamento profissional de domínio. Essa abordagem se baseia em nossa filosofia de soluções auto-hospedadas — similar à forma como mostramos que é possível auto-hospedar o n8n para automação de workflows e construir stacks de desenvolvimento multi-tenant para controle operacional completo.

O Problema com Implantações React Tradicionais

A maioria dos tutoriais de implantação React pula os detalhes críticos de produção. Você encontra guias mostrando npm run build e copiando arquivos para o nginx, mas raramente cobrem:

Conflitos de Configuração:

  • Roteadores HTTP personalizados que sobrescrevem redirecionamentos globais
  • Erros de sintaxe em labels do Traefik que causam falhas silenciosas
  • Problemas de binding IPv6 vs IPv4 em verificações de saúde
  • Mapeamentos de porta de serviço ausentes que produzem erros 404

Gerenciamento de Recursos:

  • Erros de disco cheio impedindo o registro de containers
  • Inchaço de imagens Docker por artefatos de build desnecessários
  • Estratégias de cache ineficientes que atrasam implantações
  • Restrições de memória afetando desempenho de build

Prontidão para Produção:

  • Automação adequada de certificados SSL
  • Estratégias de implantação sem downtime
  • Configurações de verificação de saúde
  • Integração de logging e monitoramento

O resultado? Horas desperdiçadas depurando por que um app que funciona perfeitamente localmente retorna erros 404 misteriosos em produção, mesmo que "tudo pareça correto."

As Ferramentas Que Estamos Usando

Vamos entender o que cada peça faz em nossa arquitetura de implantação React simplificada:

Vite: Ferramenta de Build Moderna

O Vite proporciona desenvolvimento ultra rápido e builds de produção otimizados. Diferente do Create React App, o Vite aproveita módulos ES nativos durante o desenvolvimento e gera bundles altamente otimizados para produção. Sua aplicação React compila em segundos em vez de minutos.

A vantagem principal? O Vite automaticamente cuida de code splitting, tree shaking e otimização de assets. Você obtém builds prontos para produção sem configurações complexas de webpack.

Docker: Containerização para Consistência

O Docker garante que sua aplicação React rode de forma idêntica em desenvolvimento e produção. O mesmo container nginx servindo seu app localmente se comportará exatamente da mesma forma no seu servidor de produção — eliminando o clássico problema "funciona na minha máquina".

Pense no Docker como o empacotamento de todo o ambiente da sua aplicação (arquivos de build React, configuração nginx e runtime) em um container portátil que funciona em qualquer lugar.

Traefik: Proxy Reverso Inteligente

O Traefik age como um direcionador de tráfego inteligente, roteando automaticamente requisições para as aplicações containerizadas corretas com base em nomes de domínio. Em vez de configurar manualmente regras complexas de nginx ou Apache para cada nova aplicação, o Traefik lê labels dos seus containers Docker e configura o roteamento automaticamente.

Em nossa configuração Docker multi-tenant, demonstramos o poder do Traefik para gerenciar múltiplos ambientes de clientes. Os mesmos princípios se aplicam aqui para gerenciar múltiplas aplicações React em um único servidor.

A beleza é que o Traefik cuida da terminação SSL via Let's Encrypt automaticamente, proporciona descoberta automática de serviços e oferece monitoramento detalhado — tudo com configuração mínima.

nginx: Servidor Web de Produção

O nginx serve seus arquivos estáticos de build React com desempenho excepcional. É o padrão de fato para servir conteúdo estático em produção, lidando com milhares de conexões simultâneas eficientemente enquanto usa recursos mínimos.

Entendendo o Fluxo de Implantação

Aqui está a jornada completa do desenvolvimento local à produção:

  1. Desenvolvimento Local: Construa e teste sua aplicação React com npm run dev
  2. Build de Produção: Crie arquivos estáticos otimizados com npm run build
  3. Containerização: Empacote arquivos de build no container Docker nginx
  4. Implantação no Servidor: Faça upload e inicie o container no servidor de produção
  5. Registro no Traefik: Roteamento automático e provisionamento de certificado SSL
  6. Monitoramento de Saúde: Verificações contínuas de saúde garantem disponibilidade

O que torna isso poderoso é a automação. Uma vez configurado corretamente, você pode implantar atualizações em menos de 60 segundos com um único comando.

Configurando Sua Aplicação React

Estrutura do Projeto para Produção

Organize seu projeto React pensando na implantação:

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

Criando o Container de Produção

Configuração nginx para React

Aplicações React usam roteamento no lado do cliente, exigindo configuração especial do nginx. A peça crítica é try_files $uri $uri/ /index.html que garante que o React Router funcione corretamente em produção — todas as rotas são servidas pelo arquivo principal index.html.

Dockerfile para Produção

Isso usa nginx:alpine para uma imagem mínima de produção (apenas ~8MB) que contém tudo necessário para servir sua aplicação React.

Configuração Docker Compose

Notas Críticas de Configuração:

A seção de labels é onde muitas implantações falham. Note o que NÃO incluímos:

  • Nenhuma definição separada de roteador HTTP
  • Nenhum middleware de redirecionamento personalizado
  • Nenhuma configuração de entrypoint HTTP

Por quê? Porque a configuração global do Traefik já lida com redirecionamentos HTTP para HTTPS. Adicionar roteadores HTTP personalizados sobrescreve esse comportamento e causa erros 404 — exatamente o problema que resolvemos em nossa sessão de depuração.

Implantando no Seu Servidor de Produção

Pré-requisitos no Seu Servidor

Seu servidor de produção precisa de:

Ambiente Docker: Docker e Docker Compose instalados, Traefik rodando, rede proxy existente.

Espaço em Disco Suficiente: Você precisa de pelo menos 2-5GB livres para operações Docker.

Configuração DNS: Aponte seu domínio para o endereço IP do seu servidor e aguarde a propagação DNS.

Falhas Comuns de Implantação e Soluções

Erro 404 Apesar da Configuração Correta

Sintoma: O Traefik retorna HTTP/2 404 mesmo que o container funcione internamente.

Causa Raiz: Múltiplas definições de roteador para o mesmo serviço sem mapeamento adequado de porta de serviço, ou roteadores HTTP personalizados sobrescrevendo os redirecionamentos globais do Traefik.

O redirecionamento HTTP para HTTPS global do Traefik (configurado em traefik.yml) lida com tráfego HTTP automaticamente. Roteadores HTTP personalizados por serviço criam conflitos.

Container com Status Unhealthy

Sintoma: docker compose ps mostra container como "unhealthy"

Causa Raiz: Verificação de saúde usando localhost que resolve para IPv6 [::1], mas nginx escutando apenas em IPv4.

Solução: Use endereço IPv4 explícito http://127.0.0.1:80/health em vez de localhost.

Erros 404 do React Router ao Recarregar

Sintoma: App funciona no carregamento inicial mas mostra 404 ao recarregar em rotas como /about

Causa Raiz: Falta da diretiva try_files na configuração nginx

Solução: Garanta que seu nginx.conf inclua try_files $uri $uri/ /index.html; que instrui o nginx a servir index.html para todas as rotas, deixando o React Router lidar com o roteamento no lado do cliente.

Otimizando para Produção

Implemente implantações sem downtime, verificações de saúde avançadas, otimização de desempenho e limites de recursos. O nginx servindo arquivos estáticos React requer recursos mínimos — 512MB de memória e meio núcleo de CPU lidam com milhares de usuários simultâneos.

Por Que Implantações Docker Auto-Hospedadas Importam

Auto-hospedar suas aplicações React em infraestrutura Docker proporciona controle completo sobre seu pipeline de implantação sem vendor lock-in. Você pode implantar aplicações ilimitadas em sua própria infraestrutura, personalizar cada aspecto do processo de implantação e integrar perfeitamente com seus serviços auto-hospedados existentes.

Essa abordagem funciona particularmente bem quando combinada com nossa arquitetura Docker multi-tenant, onde você pode hospedar múltiplas aplicações de clientes na mesma infraestrutura com isolamento completo.

Recursos Relacionados

Para mais guias de infraestrutura auto-hospedada, confira estes recursos:

Obtenha Suporte Profissional

Se você está implementando infraestrutura de implantação React para uso em produção ou precisa de personalização para suas necessidades específicas de entrega para clientes, podemos ajudar com pipelines de implantação personalizados, integração com sistemas CI/CD existentes, otimização de desempenho e estratégias de implantação multi-região.

Entre em contato através de tva.sg/contact para discutir suas necessidades de implantação React e obter orientação profissional sobre implementação.