Configuring Environment Secrets, Persistent PostgreSQL, and Custom Domains in Replit Deployments

Deploying a web application from a development workspace to a production environment requires three essential pillars: secure credential isolation, persistent and resilient relational data storage, and branded, encrypted domain routing. In Replit, transforming an interactive prototype into a production-ready application centers around Replit Deployments (accessible via the Publishing tool). Rather than treating hosting as an afterthought, Replit integrates compute provisioning, serverless PostgreSQL, secret management, and automated TLS certificate handling into a single deployment pipeline.

This guide walks through configuring environment secrets, setting up persistent PostgreSQL databases, and wiring custom domains with permanent SSL/TLS verification in Replit Deployments.

1. Choosing the Right Deployment Architecture

Before configuring storage or credentials, you must select the deployment model suited to your workload under Publishing → Adjust settings → Deployment type:

• Autoscale (Recommended for Web Apps & APIs): The default deployment type. Instances automatically scale up to handle incoming traffic spikes and scale down to zero when idle, minimizing compute costs. Ideal for dynamic full-stack frameworks (Express, Next.js, FastAPI, Django, Ruby on Rails).
• Reserved VM (Always-On Servers & Workers): Provisions a dedicated virtual machine with continuous uptime, predictable monthly pricing, and unthrottled CPU/memory. Best for applications maintaining persistent WebSocket connections, background job queues, or scheduled background bots.
• Static: Distributes static client files (HTML, CSS, JS) over global cache servers without a backend runtime. (Note: Static deployments do not execute server code or attach database drivers).

For most web services requiring relational persistence and secret management, Autoscale or Reserved VM is the appropriate foundation.

2. Managing Production Environment Secrets

A common vulnerability during deployment is the leakage or mismatch of API keys, authentication credentials, and service tokens. Replit separates your workspace into two distinct secret scopes: Development Secrets and Deployment Secrets.

Understanding Secret Scopes

• Development Secrets: Configured in the Project Editor via the Secrets tool (the lock icon). These environment variables are only accessible during live coding, testing, and previews inside the workspace.
• Deployment Secrets: Injected into the published container instances during build and runtime. While Replit automatically pre-populates deployment settings with your workspace secrets upon first publish, modifications made in the editor workspace do not automatically propagate to an already running deployment.

Step-by-Step Configuration

1. Audit Sensitive Values: Identify third-party API credentials (Stripe, OpenAI, Clerk, OAuth client secrets) and application keys. Differentiate between sensitive Secrets (encrypted at rest with AES-256 and transmitted via TLS) and non-sensitive Configurations (such as LOG_LEVEL=info or public CDN prefixes).
2. Set Deployment Secrets: Open the Publishing tool, navigate to Adjust settings, and inspect the Deployment secrets section. Add or verify each key-value pair needed for production.
3. Trigger a Redeployment: When you update secrets in a live application, open the Publishing tool and click Publish (or re-publish). New environment variables take effect only when a new container build is deployed.

Accessing Secrets in Application Code

Secrets are injected as standard environment variables. Never hardcode fallback credentials in version control.

In Node.js / TypeScript:

const apiKey = process.env.STRIPE_SECRET_KEY;
if (!apiKey) {
  throw new Error("STRIPE_SECRET_KEY is required in production environment");
}

In Python:

import os

api_key = os.environ.get("STRIPE_SECRET_KEY")
if not api_key:
    raise RuntimeError("STRIPE_SECRET_KEY is missing from environment")

Note on System Variables: Environment variables generated exclusively for development previews (such as REPLIT_DEV_DOMAIN) are omitted in production containers. Always reference production hostnames using your custom domain configuration or custom environment variables.

3. Configuring Persistent PostgreSQL for Production

Every Replit App comes with access to managed PostgreSQL, but development and production utilize fundamentally different underlying architectures.

Architecture: Development (Helium) vs. Production (Neon)

• Development Environment (Helium): Replit runs a local PostgreSQL 16 engine directly within your workspace infrastructure. It features ultra-low latency, includes 20 GB of storage, does not require SSL connections, and isolates development experiments.
• Production Environment (Neon): When you publish, Replit provisions a dedicated, serverless PostgreSQL instance hosted on Neon. It scales to zero after five minutes of inactivity to conserve compute, instantly wakes upon receiving an incoming query, and enforces encrypted SSL connections.

Connection Management and DATABASE_URL

Replit automatically provisions and sets the DATABASE_URL environment variable in both your development workspace and production deployment:

• Never manually override DATABASE_URL in Deployment Secrets with your development connection string. Replit dynamically binds your container to the isolated production database.
• Replit has deprecated individual credentials (PGHOST, PGUSER, PGPORT, PGPASSWORD) in favor of the unified DATABASE_URL. Ensure your ORM or driver parses this single connection URI.

Solving the Production SSL Requirement

Because the local development database (Helium) does not support SSL handshakes, while production Neon PostgreSQL mandates TLS/SSL, your database client must configure SSL conditionally. Hardcoding SSL settings causes connection failures in either development or production.

Example: PostgreSQL Client Pool Configuration (Node.js pg)

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,
});

Example: Prisma or Drizzle ORM

When configuring schema connections or client wrappers:

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);

Serverless Connection Pooling

Autoscale deployments dynamically spin up multiple application replicas during sudden traffic surges. Unpooled direct connections to PostgreSQL can rapidly exhaust connection limits (max_connections).

To enable connection pooling:

1. Examine the production connection string in the Database tool settings.
2. Production databases hosted on Neon provide a pooled connection host by attaching -pooler to the host segment (for example, ep-xyz-pooler.region.neon.tech).
3. Use the pooled connection string for ephemeral query transactions in high-concurrency Autoscale deployments, while reserving direct connections for migration tasks that require session-level locking.

Safe Migrations and Deployment Previews

When applying schema migrations (such as adding non-nullable columns, altering types, or renaming tables):

• Utilize Replit's Deployment Previews to validate database migrations against an isolated copy of production before exposing changes to live users.
• Account for the brief wake-up latency of the serverless database if compute was paused due to inactivity, configuring connection timeouts (e.g., 5 to 10 seconds) gracefully in your startup scripts.

4. Connecting and Securing Custom Domains

By default, published deployments receive a free .replit.app subdomain. For commercial reliability and branding, configuring a custom domain (both root apex and subdomains) is critical.

Replit automates Let's Encrypt / Google Trust TLS/SSL certificate issuance and renewal via automated DNS validation. However, misconfigured DNS records or deleted validation tokens will cause silent renewal failures.

Step-by-Step Custom Domain Setup

1. Add Domain in the Publishing Tool

1. In the Project Editor, open Publishing → select the Domains tab.
2. Enter your custom domain (e.g., example.com).
3. Replit displays the target IP address for the A record and a custom verification string for a TXT record.

2. Configure DNS Records at Your Registrar

Log into your DNS provider (such as Cloudflare, Namecheap, GoDaddy, or AWS Route 53) and configure the following records:

3. Resolve Common DNS Pitfalls

• Keep the TXT Record Permanently: Many developers assume the TXT record is only necessary for one-time verification and delete it. Do not remove this record. Replit relies on the permanent presence of replit-verify=... to validate periodic SSL/TLS certificate renewals every 60–90 days. If the record is missing, the automated renewal fails, and your site will eventually render an invalid certificate error in web browsers.
• Remove Conflicting Records: Delete existing AAAA (IPv6) records or alternative A records pointing to previous hosts on the same root hostname. Conflicting records prevent SSL provisioning.
• Disable Third-Party Cloudflare Proxy: If your DNS is managed through Cloudflare, set the proxy status to DNS only (grey cloud) rather than Proxied (orange cloud). Active proxying intercepts ACME certificate challenges and interferes with Replit's edge ingress verification.

Configuring Subdomains and the www Redirect

Replit treats apex domains and subdomains as independent routing endpoints:

• Linking example.com does not automatically route www.example.com.
• To support both, open the Domains tab, add www.example.com as a distinct entry, and copy its specific DNS records.
• In your registrar, add an A record with hostname www pointing to the Replit IP and the subdomain-specific replit-verify=... TXT record.
• Configure an HTTP 301 canonical redirect rule at your DNS registrar level (forwarding www.example.com to example.com or vice versa) to preserve SEO authority and avoid duplicate content indexing.

5. Production Readiness Verification Checklist

Before directing live user traffic to your Replit deployment, perform this end-to-end verification:

1. Environment Secrets Audit:
   • Verify all third-party API keys exist under Publishing → Adjust settings → Deployment secrets.
   • Confirm no sensitive API keys are checked into repository files or .replit configs.
   • Trigger a clean deployment build to apply secret updates.
2. Database Resilience & Connectivity:
   • Ensure database connection code handles TLS/SSL conditionally (rejectUnauthorized: false when NODE_ENV === "production").
   • Confirm the application relies on the system-injected DATABASE_URL rather than hardcoded connection parameters.
   • Verify that migrations run cleanly during deployment startup without hanging.
3. Domain & Security Health:
   • Verify that both apex and www domains display the Verified status badge in the Replit Domains tab.
   • Confirm HTTPS loads with a valid certificate across desktop and mobile browsers.
   • Ensure the replit-verify TXT record remains saved in your registrar DNS management table.
4. Monitoring & Health Checks:
   • Enable the built-in Monitoring tools in the Publishing pane to receive instant email notifications upon downtime or elevated HTTP error rates.
   • Choose a Deployment geography close to your primary audience (note: once deployed, geography is fixed to that instance).

By isolating secrets between development and deployment, wrapping database drivers in environment-aware SSL wrappers, and maintaining permanent DNS validation records, you establish a resilient, scalable, and secure production foundation on Replit.

References

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