Configuración de Secrets, PostgreSQL Persistente y Dominios Personalizados en Replit Deployments para Producción

El paso de un prototipo interactivo a una aplicación web en producción exige resolver tres requisitos de infraestructura esenciales: la gestión segura de credenciales, una base de datos relacional persistente y resistente, y el enrutamiento a través de un dominio de marca con certificados TLS/SSL totalmente gestionados. En el ecosistema de Replit, este flujo se centraliza en Replit Deployments (dentro de la herramienta Publishing del editor). Replit integra la orquestación de contenedores, PostgreSQL sin servidor, custodia de secretos y validación DNS para certificados en un único flujo de entrega continua.

Esta guía detalla cómo configurar variables de entorno seguras (Deployment Secrets), aprovisionar bases de datos PostgreSQL persistentes resolviendo incompatibilidades de SSL, y conectar dominios personalizados manteniendo renovaciones automáticas permanentes de certificados en Replit Deployments.

1. Selección del Modelo de Arquitectura de Despliegue

Antes de gestionar datos o credenciales, es necesario seleccionar el tipo de despliegue adecuado en el editor mediante Publishing → Adjust settings → Deployment type:

• Autoscale (Recomendado para aplicaciones web y APIs): Es el tipo predeterminado. Los contenedores escalan horizontalmente de forma automática para absorber picos de tráfico y se reducen a cero en periodos de inactividad, optimizando los costes de cómputo. Es ideal para aplicaciones en Node.js/Express, Next.js, FastAPI, Django o Ruby on Rails.
• Reserved VM (Servidores y procesos en segundo plano siempre activos): Asigna una máquina virtual dedicada con tiempo de actividad continuo, coste mensual fijo y recursos de CPU/RAM garantizados. Resulta idóneo para servidores con conexiones WebSocket permanentes, colas de tareas en segundo plano (Celery, BullMQ) o bots interactivos.
• Static (Sitios estáticos): Distribuye activos前端 (HTML/CSS/JS) mediante redes de distribución de contenido (CDN) globales. No ejecuta código de servidor ni permite conexiones dinámicas a bases de datos.

Para aplicaciones comerciales que necesitan persistencia en PostgreSQL y gestión de credenciales, Autoscale o Reserved VM constituyen la base arquitectónica adecuada.

2. Gestión Aislada de Variables de Entorno y Secrets

Uno de los fallos más críticos en producción radica en la exposición accidental de credenciales o la mezcla entre entornos de desarrollo y producción. Replit organiza las variables en dos ámbitos claramente diferenciados: Development Secrets y Deployment Secrets.

Entendiendo los Dos Ámbitos

• Development Secrets (Secretos de desarrollo): Se configuran en la barra de herramientas del editor mediante la herramienta Secrets (icono de candado). Estas variables solo se inyectan en el entorno de pruebas, depuración y vista previa dentro del espacio de trabajo.
• Deployment Secrets (Secretos de despliegue): Se inyectan exclusivamente durante la compilación y ejecución de los contenedores en producción. Aunque Replit copia inicialmente los secretos del espacio de trabajo al crear el primer despliegue, los cambios posteriores efectuados en el editor no se sincronizan de forma automática con un despliegue que ya se encuentra en ejecución.

Procedimiento de Configuración

1. Clasificación de credenciales: Separe las claves sensibles (claves de API de Stripe, tokens de OpenAI, credenciales OAuth) de las opciones de configuración no sensibles. Los valores confidenciales deben almacenarse como Secrets (cifrados con AES-256 en reposo y TLS en tránsito), mientras que variables como LOG_LEVEL=info o URLs de CDN públicas deben ir en Configurations.
2. Definición en la herramienta Publishing: Abra Publishing, acceda a Adjust settings y localice la sección Deployment secrets. Introduzca o verifique las parejas clave-valor destinadas a producción.
3. Republicación obligatoria (Re-publish): Tras actualizar los secretos de despliegue, haga clic en Publish para recompilar el contenedor y aplicar las nuevas variables en producción.

Acceso a las Variables en el Código

Los secretos se exponen como variables de entorno estándar del sistema operativo. Evite incluir claves de respaldo fijas en el código fuente.

Ejemplo en Node.js / TypeScript:

const stripeApiKey = process.env.STRIPE_SECRET_KEY;
if (!stripeApiKey) {
  throw new Error("STRIPE_SECRET_KEY no está configurada en producción");
}

Ejemplo en Python:

import os

stripe_api_key = os.environ.get("STRIPE_SECRET_KEY")
if not stripe_api_key:
    raise RuntimeError("STRIPE_SECRET_KEY no está configurada en producción")

Aviso sobre variables del sistema: Determinadas variables exclusivas del editor (como REPLIT_DEV_DOMAIN) no existen en los contenedores de producción. Para construir URLs de redirección o webhooks, utilice su propio dominio personalizado o variables de entorno explícitas.

3. Configuración de PostgreSQL Persistente para Producción

Cualquier proyecto de Replit incluye soporte nativo para PostgreSQL, pero el motor subyacente difiere sustancialmente entre el entorno de desarrollo y el de producción.

Arquitectura: Entorno de Desarrollo (Helium) vs. Producción (Neon)

• Base de datos de desarrollo (Infraestructura Helium): Se ejecuta localmente dentro de la infraestructura interna de Replit junto a su espacio de trabajo. Ofrece latencia mínima y 20 GB de almacenamiento. La red interna de Helium no admite negociaciones de conexión SSL.
• Base de datos de producción (Motor Serverless Neon): Al publicar, Replit aprovisiona una instancia dedicada de PostgreSQL sin servidor gestionada por Neon. Tras 5 minutos sin recibir consultas, el motor entra en estado de suspensión para detener el consumo de cómputo, reactivándose al instante ante una nueva consulta. Neon exige de forma obligatoria conexiones cifradas mediante SSL/TLS.

Inyección Automática de DATABASE_URL

Replit gestiona automáticamente la variable DATABASE_URL:

• Nunca sobrescriba manualmente DATABASE_URL en Deployment Secrets con la cadena de desarrollo. Replit asigna de forma dinámica la cadena de conexión de producción al contenedor.
• Los parámetros individuales de conexión (PGHOST, PGPORT, PGUSER, PGPASSWORD) han sido retirados. Los ORMs (Prisma, Drizzle, TypeORM) y controladores deben conectarse directamente a través de la URI DATABASE_URL.

Patrón para Manejar la Restricción de SSL en Producción

El intento de forzar SSL en desarrollo provoca errores del tipo The server does not support SSL connections, mientras que desactivar SSL en producción genera fallos de autenticación con Neon. La solución consiste en parametrizar la conexión según el valor de NODE_ENV:

Configuración con el paquete 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,
});

Configuración con 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);

Gestión de Concurrencia y Connection Pooling

En despliegues de tipo Autoscale, una repentina afluencia de visitas levanta múltiples réplicas de la aplicación. Conexiones directas sin gestión de reservas pueden agotar rápidamente el límite de conexiones del motor (max_connections).

1. En la herramienta Database de Replit, consulte los detalles de la base de datos de producción.
2. Neon proporciona un endpoint con multiplexación de conexiones (añadiendo -pooler al host, por ejemplo ep-xyz-pooler.region.neon.tech).
3. Emplee la cadena con pooling para las consultas habituales de la API web, y reserve la conexión directa estándar para migraciones o tareas de esquema que requieran bloqueos a nivel de sesión.

Migraciones Seguras y Deployment Previews

Al aplicar modificaciones en la estructura de las tablas (eliminación de columnas, alteraciones de tipo o adición de campos requeridos sin valor por defecto):

• Utilice las Deployment Previews para ejecutar y comprobar las migraciones sobre una réplica aislada de producción antes de desplegar hacia los usuarios finales.
• Tenga en cuenta el tiempo de reactivación si la base de datos estaba inactiva; configure márgenes de tiempo razonables (por ejemplo, 5 a 10 segundos) en los reintentos de conexión durante el arranque de la app.

4. Conexión de Dominios Personalizados y Certificados TLS/SSL

Las aplicaciones desplegadas reciben por defecto un subdominio bajo *.replit.app. Para proyectos en producción, es imprescindible vincular un dominio personalizado propio (tanto el dominio raíz o apex como sus subdominios).

Replit automatiza la emisión y renovación periódica de certificados TLS/SSL (mediante Let's Encrypt / Google Trust) a través de validación DNS. No obstante, una mala configuración de registros puede interrumpir este proceso.

Guía de Configuración DNS

1. Registrar el dominio en Publishing

1. Abra la herramienta Publishing y acceda a la pestaña Domains.
2. Introduzca el dominio personalizado deseado (por ejemplo, example.com).
3. El panel facilitará la dirección IP para el registro A y una cadena de texto para el registro de verificación TXT.

2. Configurar los registros en el proveedor de DNS

Acceda al panel de su registrador o proveedor DNS (Cloudflare, Namecheap, GoDaddy, Route 53) y cree los siguientes registros:

3. Reglas Críticas para Evitar Caídas del Servicio

• Mantenga el registro TXT de forma permanente: El error más habitual consiste en borrar el registro TXT una vez completada la verificación inicial. Nunca elimine este registro. Replit efectúa la renovación automática de los certificados cada 60–90 días valiéndose de este registro replit-verify=.... Si se elimina, la siguiente renovación fallará en silencio y, al caducar el certificado vigente, los navegadores bloquearán el acceso a los usuarios con advertencias de seguridad.
• Elimine registros en conflicto: Borre cualquier registro A antiguo hacia otros servidores y suprima todos los registros AAAA (IPv6) existentes en el dominio raíz, ya que estos últimos bloquean la emisión de certificados en la pasarela de Replit.
• Desactive el proxy en Cloudflare: Si utiliza Cloudflare, configure el registro en modo DNS only (nube gris). El proxy activo (nube naranja) intercepta las llamadas ACME e impide la verificación de Replit.

Subdominios y Redirección Canónica de www

Replit trata el dominio raíz y los subdominios como entidades independientes:

• Vincular example.com no habilita automáticamente www.example.com.
• Para ofrecer ambas opciones, añada www.example.com como un registro separado en la pestaña Domains, configurando el registro A y el registro TXT específico para el host www.
• Configure una redirección canónica 301 en su proveedor de DNS (de www a raíz, o viceversa) para unificar la reputación SEO y evitar indexaciones duplicadas.

5. Lista de Comprobación para Producción

Antes de dirigir usuarios reales a la aplicación, verifique los siguientes puntos:

1. Auditoría de Secrets:
   • Compruebe en Publishing → Adjust settings → Deployment secrets que todas las claves requeridas están presentes.
   • Confirme que no existen claves maestras en el repositorio de código.
   • Ejecute una republicación completa tras modificar secretos.
2. Resiliencia de la Base de Datos:
   • El código de conexión activa SSL condicionalmente cuando NODE_ENV === "production".
   • La aplicación utiliza la variable inyectada DATABASE_URL sin modificaciones locales.
   • Las migraciones y consultas responden sin agotar las conexiones máximas del servidor.
3. Dominio y Estado Criptográfico:
   • La pestaña Domains de Replit muestra la etiqueta verde Verified.
   • El registro replit-verify TXT permanece guardado en su panel DNS.
   • La navegación HTTPS funciona sin errores de certificado en ordenadores y dispositivos móviles.
4. Supervisión y Ubicación:
   • Active las herramientas de monitorización (Monitoring tools) en el panel de Publishing para recibir alertas por correo ante caídas del servicio.
   • Confirme que la región geográfica seleccionada (Deployment geography) se encuentra próxima a sus usuarios (una vez desplegada, la región queda fijada).

Al estructurar correctamente las credenciales por entorno, adoptar clientes PostgreSQL compatibles con SSL en producción y conservar de forma permanente los registros de validación DNS, su aplicación en Replit Deployments contará con un entorno de producción seguro, escalable y resistente.

Referencias

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