Configurando Secrets de Ambiente, PostgreSQL Persistente e Domínios Personalizados no Replit Deployments para Produção

A transição de um protótipo interativo para uma aplicação web em produção exige o alinhamento de três pilares de infraestrutura fundamentais: gestão e isolamento de credenciais sensíveis, persistência confiável em banco de dados relacional e roteamento seguro sob domínio próprio com certificados TLS/SSL totalmente gerenciados. No ecossistema do Replit, esse processo é unificado por meio do Replit Deployments (acessível pela ferramenta Publishing no editor). A plataforma combina provisionamento de contêineres, PostgreSQL serverless, cofre de chaves e automação de certificados DNS/TLS em um único fluxo de entrega contínua.

Este guia orienta desenvolvedores na configuração de variáveis de ambiente seguras (Deployment Secrets), na estruturação de instâncias persistentes do PostgreSQL com conexão SSL resiliente e no apontamento correto de domínios personalizados com renovação contínua de certificados.

1. Escolhendo a Arquitetura de Deploy Correta

Antes de gerenciar variáveis e bancos de dados, o desenvolvedor deve selecionar o modelo de implantação ideal para a sua carga de trabalho em Publishing → Adjust settings → Deployment type:

• Autoscale (Recomendado para aplicações web e APIs): O modelo padrão. Os contêineres escalam horizontalmente de forma automática para absorver aumentos de tráfego e reduzem a capacidade a zero quando ociosos, diminuindo substancialmente os custos de computação. Ideal para aplicações full-stack em Node.js/Express, Next.js, FastAPI, Django ou Ruby on Rails.
• Reserved VM (Servidores e processos em segundo plano dedicados): Provisiona uma máquina virtual dedicada com operação contínua, custo mensal fixo previsível e alocação exclusiva de CPU e memória. Recomendado para servidores com conexões WebSocket persistentes, filas de tarefas (Celery, BullMQ) ou bots que não podem entrar em suspensão.
• Static (Sites estáticos): Distribui arquivos de interface (HTML/CSS/JS) via servidores de cache global sem camada de execução de backend. Não oferece suporte à execução de código de servidor nem a conexões com bancos de dados.

Para aplicações comerciais convencionais que leem e escrevem em bancos de dados relacionais e demandam proteção de credenciais, o Autoscale ou a Reserved VM é a escolha recomendada.

2. Gerenciando Variáveis de Ambiente e Secrets em Produção

Erros comuns de implantação costumam envolver vazamento de chaves privadas ou conflito de credenciais entre os ambientes de teste e produção. O Replit resolve essa questão separando o ciclo de vida das variáveis em dois escopos rigorosamente isolados: Development Secrets e Deployment Secrets.

Entendendo os Escopos de Segredos

• Development Secrets (Segredos de Desenvolvimento): Definidos no editor por meio da ferramenta Secrets (ícone de cadeado). Essas variáveis são injetadas exclusivamente no espaço de trabalho de desenvolvimento, nos testes locais e nas visualizações prévias interativas.
• Deployment Secrets (Segredos de Implantação): Injetados unicamente durante o build e a execução dos contêineres em produção. Embora o Replit replique os segredos do workspace na primeira vez em que a aplicação é publicada, qualquer alteração posterior realizada no editor não será aplicada automaticamente a um deploy que já está no ar.

Passo a Passo de Configuração

1. Separação de Chaves Sensíveis e Configurações: Separe credenciais de serviços externos (chaves de API da Stripe, tokens da OpenAI, segredos de autenticação OAuth) de valores normais. Credenciais críticas devem ser armazenadas como Secrets (com criptografia AES-256 em repouso e transmissão via TLS), enquanto parâmetros não sigilosos, como LOG_LEVEL=info ou URLs públicas de CDN, podem ser incluídos na seção Configurations.
2. Definição em Deployment Secrets: Abra a ferramenta Publishing, clique em Adjust settings e localize a seção Deployment secrets. Insira ou atualize os pares de chave e valor necessários para o ambiente de produção.
3. Republicação Necessária (Re-publish): Após atualizar as variáveis de deploy, clique no botão Publish para recompilar o contêiner e ativar as novas variáveis em produção.

Consumindo as Variáveis no Código

Os segredos são injetados como variáveis padrão de ambiente do sistema operacional. Nunca insira credenciais de fallback no controle de versão.

Exemplo em Node.js / TypeScript:

const stripeKey = process.env.STRIPE_SECRET_KEY;
if (!stripeKey) {
  throw new Error("STRIPE_SECRET_KEY não foi encontrada no ambiente de produção");
}

Exemplo em Python:

import os

stripe_key = os.environ.get("STRIPE_SECRET_KEY")
if not stripe_key:
    raise RuntimeError("STRIPE_SECRET_KEY não foi encontrada no ambiente de produção")

Atenção: Variáveis geradas exclusivamente para testes no editor (como REPLIT_DEV_DOMAIN) não existem no ambiente de produção. Para montar URLs de callback ou redirecionamento, utilize seu domínio personalizado ou defina variáveis de ambiente customizadas.

3. Configuração do PostgreSQL Persistente em Produção

Todo Replit App dispõe de suporte integrado ao PostgreSQL, mas as infraestruturas de desenvolvimento e produção funcionam com mecanismos distintos.

Arquitetura: Desenvolvimento (Helium) vs. Produção (Neon)

• Banco de Desenvolvimento (Infraestrutura Helium): Roda na infraestrutura local do próprio Replit, ao lado do workspace. Oferece latência ultrabaixa e 20 GB de espaço de armazenamento. A rede local do Helium não suporta handshakes de conexão SSL.
• Banco de Produção (Arquitetura Serverless Neon): Ao publicar o projeto, o Replit provisiona automaticamente uma instância dedicada de PostgreSQL serverless fornecida pela Neon. O banco entra em modo de suspensão após 5 minutos sem consultas (pausando custos de computação) e acorda instantaneamente ao receber novas requisições. O Neon exige conexões criptografadas com SSL/TLS de forma mandatória.

Gerenciamento de DATABASE_URL

O Replit gerencia a variável DATABASE_URL de ponta a ponta:

• Não sobrescreva manualmente a variável DATABASE_URL nos Deployment Secrets com a URL de desenvolvimento. No deploy, o Replit injeta dinamicamente a string da base de dados de produção.
• Variáveis individuais de conexão (PGHOST, PGPORT, PGUSER, PGPASSWORD) foram descontinuadas. Todos os ORMs (Prisma, Drizzle, TypeORM) e drivers devem ser configurados para consumir a URI unificada de DATABASE_URL.

Tratamento Condicional de SSL para Produção

Tentar forçar conexões com SSL no ambiente de desenvolvimento causará o erro The server does not support SSL connections. Por outro lado, desativar o SSL em produção impedirá a conexão com o banco Neon. A solução padrão consiste em aplicar o SSL condicionalmente conforme a variável NODE_ENV:

Exemplo com o driver pg (Node.js):

import { Pool } from "pg";

const isProduction = process.env.NODE_ENV === "production";

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: isProduction ? { rejectUnauthorized: false } : false,
});

Exemplo com Drizzle ORM:

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: process.env.NODE_ENV === "production" ? { rejectUnauthorized: false } : false,
});

export const db = drizzle(pool);

Otimização com Pool de Conexões (Connection Pooling)

Sob o modelo Autoscale, picos de requisições criam réplicas instantâneas da aplicação. Se cada contêiner abrir dezenas de conexões diretas ao banco, o limite de conexões (max_connections) do PostgreSQL será atingido rapidamente.

1. Abra a ferramenta Database no editor do Replit para verificar os dados do banco de produção.
2. O Neon oferece um endpoint com pool de conexões ativo, contendo o sufixo -pooler no host (por exemplo, ep-xyz-pooler.region.neon.tech).
3. Utilize o endpoint pooler para o tráfego regular de consultas da aplicação web, reservando a conexão direta não agregada apenas para migrações de esquema que demandem travas no nível de sessão.

Migrações Seguras e Deployment Previews

Ao realizar alterações de estrutura (remoção de colunas, modificação de tipos de dados ou adição de campos obrigatórios sem valor padrão):

• Use as Deployment Previews para testar e validar os scripts de migração em uma cópia segura e isolada do banco de produção antes de aplicar alterações nos dados reais dos usuários.
• Considere a leve latência de inicialização caso o banco tenha entrado em suspensão por inatividade, ajustando timeouts de inicialização (entre 5 e 10 segundos) nos scripts de inicialização da aplicação.

4. Apontamento de Domínios Personalizados e Certificados SSL/TLS

As aplicações publicadas no Replit recebem um subdomínio gratuito no formato *.replit.app. No entanto, aplicações comerciais em produção exigem o uso de um domínio próprio (tanto o domínio raiz quanto subdomínios como www).

O Replit automatiza a emissão e renovação periódica de certificados TLS/SSL (via Let's Encrypt / Google Trust) por meio de validação de DNS. A configuração incorreta desses registros pode impedir a emissão de novos certificados ou provocar falhas durante a renovação.

Configuração Passo a Passo

1. Inserir o domínio na ferramenta Publishing

1. Acesse a ferramenta Publishing e selecione a aba Domains.
2. Digite o domínio personalizado registrado (por exemplo, example.com).
3. O Replit exibirá o endereço IP de destino para o registro A e uma chave de validação para o registro TXT.

2. Configurar os registros DNS no provedor

Acesse o painel do seu registrador de domínio ou servidor DNS (Cloudflare, Registro.br, Namecheap, GoDaddy, Route 53) e crie os seguintes registros:

3. Cuidados Essenciais com o DNS

• Mantenha o registro TXT permanentemente ativo: Este é o erro mais recorrente entre desenvolvedores. Muitos acreditam que o registro TXT só é necessário para a validação inicial e o removem em seguida. Nunca apague esse registro. O Replit utiliza o replit-verify=... para renovar os certificados automaticamente a cada 60 a 90 dias. Sem esse registro ativo no DNS, a renovação falhará silenciosamente e os navegadores passarão a exibir alertas de conexão insegura quando o certificado atual expirar.
• Remova registros concorrentes: Exclua registros A antigos e quaisquer registros AAAA (IPv6) configurados na raiz do domínio. Entradas IPv6 adicionais interferem no processo de validação de certificados do gateway de borda do Replit.
• Desative o Proxy do Cloudflare (Nuvem Laranja): Caso gerencie o DNS pela Cloudflare, marque o registro como DNS only (nuvem cinza). O modo proxy intermediário interfere nos desafios do protocolo ACME e bloqueia a validação direta do Replit.

Subdomínios e Redirecionamento Canônico de www

Na infraestrutura do Replit, o domínio raiz e os subdomínios são entidades tratadas separadamente:

• Adicionar example.com não roteia automaticamente www.example.com.
• Para permitir o acesso de ambas as formas, registre www.example.com como um item independente na aba Domains, obtendo seu registro A correspondente e o registro TXT específico sob o host www.
• Configure uma regra de redirecionamento 301 permanente no seu provedor de DNS (encaminhando www para a raiz, ou vice-versa), garantindo a unificação de autoridade SEO e evitando páginas duplicadas.

5. Checklist de Prontidão para Produção

Antes de liberar sua aplicação para os usuários finais, realize a seguinte validação geral:

1. Auditoria de Variáveis e Segredos:
   • Certifique-se de que todas as chaves de API necessárias estão presentes em Publishing → Adjust settings → Deployment secrets.
   • Garanta que nenhuma chave privada esteja exposta em arquivos do repositório.
   • Conclua uma nova publicação (Re-publish) para garantir que as variáveis estejam ativas nos contêineres.
2. Conexão Segura com o Banco de Dados:
   • Valide se o driver do PostgreSQL ativa o SSL condicionalmente quando NODE_ENV === "production".
   • Verifique se a aplicação consome a variável DATABASE_URL injetada automaticamente.
   • Confirme que as consultas e migrações são executadas sem erros de conexão ou exaustão de conexões simultâneas.
3. Domínios e Validação Criptográfica:
   • Verifique se o domínio configurado apresenta a etiqueta verde Verified na aba Domains.
   • Assegure que o registro replit-verify TXT continua registrado na tabela de DNS do provedor.
   • Teste a abertura do site em computadores e celulares para confirmar o carregamento com HTTPS válido.
4. Monitoramento e Escolha de Região:
   • Ative a opção de monitoramento (Monitoring tools) no painel Publishing para receber notificações imediatas em caso de instabilidade ou erros HTTP.
   • Confira a região de hospedagem (Deployment geography) para garantir menor latência aos seus usuários principais (a região fica fixada após a publicação inicial).

Ao separar com rigor os segredos de desenvolvimento e produção, parametrizar o suporte a SSL nas conexões do PostgreSQL e manter os registros de validação DNS permanentes, sua aplicação no Replit Deployments terá uma base de produção segura, estável e escalável.

Referências

• Publishing - Replit
• Secrets - Replit
• Development and production databases - Replit
• Custom Domains - Replit
• Deployment types - Replit