Deploy on Replit

Auto-generate your docs

Overview
Prerequisites
Deployment Steps
Custom Domain Setup
Replit-Specific Configuration
Automatic Environment Detection
OIDC Authentication Flow
Session Management
Port Configuration
Environment Validation
Deployment Checklist
Troubleshooting
OIDC Authentication Fails
Database Connection Errors
File Upload Failures
Application Won’t Start
Performance Optimization
Enable Connection Pooling
Monitor Resource Usage
Enable Always On (Paid Plans)
Security Best Practices
Scaling Considerations
Database Scaling
File Storage Scaling
Application Scaling
Next Steps

Overview

Replit is the primary deployment platform for JOIP Web Application, offering seamless hosting with built-in authentication, automatic HTTPS, and zero-configuration deployment. This guide covers the complete deployment process from initial setup to production.

Prerequisites

Before deploying to Replit, ensure you have:

A Replit account (free or paid)
PostgreSQL database (Neon recommended)
Supabase project for file storage
Required API keys (Reddit, AI providers)
Basic understanding of environment variables

Deployment Steps

Create New Repl

Log in to Replit
Click “Create Repl”
Select “Import from GitHub” or upload your code
Choose Node.js as the language
Name your Repl (e.g., “joip-production”)

Configure Environment Variables

Navigate to the Secrets tab (Tools → Secrets) and add all required environment variables. See the Environment Variables page for the complete reference.Critical Variables:

DATABASE_URL=postgresql://user:password@host:5432/database
SESSION_SECRET=your-secure-random-string
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key

Configure Replit OIDC Authentication

Replit provides built-in OpenID Connect (OIDC) authentication. Configure these variables:

REPLIT_DOMAINS=your-repl.replit.app
REPL_ID=your-repl-id
ISSUER_URL=https://identity.util.repl.co

REPLIT_DOMAINS supports multiple domains separated by commas
REPL_ID is automatically populated by Replit
The app prioritizes app.joip.io if present in domains

The application automatically detects Replit environment and enables OIDC when REPLIT_DOMAINS is set.

Install Dependencies

Run the following command in the Replit Shell:

npm install

This installs all dependencies defined in package.json.

Setup Database Schema

Apply database migrations to create all required tables:

npm run db:push

This command uses Drizzle ORM to synchronize your database schema with the definitions in shared/schema.ts.

Always backup your database before running migrations in production.

Build Production Bundle

Create optimized production builds:

npm run build

This command:

Bundles the React client with Vite → dist/public/
Compiles the Express server with esbuild → dist/index.js
Optimizes assets for production delivery

Configure Replit Run Command

In .replit file, set the run command:

run = "npm start"

Or use the Replit interface:

Click the three dots next to “Run”
Select “Configure the run button”
Set command to npm start

Start the Application

Click the Run button or execute:

npm start

The server will start on port 5000, and Replit will automatically proxy it to your public domain.

Custom Domain Setup

Replit supports custom domains for paid plans:

Add Custom Domain

Open your Repl settings
Navigate to Domains
Click “Add custom domain”
Enter your domain (e.g., app.joip.io)

Configure DNS

Add the following DNS records at your domain registrar:

Type: CNAME
Name: app (or your subdomain)
Value: your-repl.replit.app

Update Environment Variables

Add your custom domain to REPLIT_DOMAINS:

REPLIT_DOMAINS=app.joip.io,your-repl.replit.app

The application will prioritize app.joip.io for authentication callbacks.

Replit-Specific Configuration

Automatic Environment Detection

The application automatically detects Replit deployment through environment variables:

// server/environmentConfig.ts:26
if (process.env.REPLIT_DOMAINS) {
  // Production Replit environment
  const domains = process.env.REPLIT_DOMAINS.split(',').map(d => d.trim());
  const primaryDomain = domains.find(d => d === 'app.joip.io') || domains[0];
}

OIDC Authentication Flow

When REPLIT_DOMAINS is set, the application uses Passport.js with Replit OIDC strategy:

User clicks “Login with Replit”
Redirect to Replit’s identity service
User authorizes the application
Callback to /api/callback with auth code
Exchange code for user profile
Create/update user in database
Establish session with secure cookies

# Required for Replit OIDC
REPLIT_DOMAINS=app.joip.io,backup.replit.app
REPL_ID=abc123-xyz789
ISSUER_URL=https://identity.util.repl.co

Session Management

Replit deployments use secure session cookies:

app.use(session({
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: true,        // HTTPS only (auto-enabled on Replit)
    httpOnly: true,      // Prevent XSS attacks
    maxAge: 30 * 24 * 60 * 60 * 1000  // 30 days
  }
}));

Port Configuration

JOIP always runs on port 5000 regardless of environment:

// server/environmentConfig.ts:29
const defaultPort = 5000;
const port = parseInt(process.env.PORT || String(defaultPort), 10);

Replit automatically proxies port 5000 to your public domain with HTTPS.

Do not change the port number. Replit’s internal proxy expects port 5000.

Environment Validation

The application validates environment setup on startup:

// server/environmentConfig.ts:89
export function validateEnvironmentSetup() {
  const errors: string[] = [];
  const warnings: string[] = [];

  if (config.isProduction && !process.env.REPL_ID) {
    errors.push('REPL_ID is required for Replit Auth in production');
  }

  if (!process.env.DATABASE_URL) {
    errors.push('DATABASE_URL is required');
  }

  // ... additional validation
}

Check startup logs for validation errors or warnings.

Deployment Checklist

Troubleshooting

OIDC Authentication Fails

Symptoms: Login redirects fail or show errors Solutions:

Verify REPLIT_DOMAINS includes your actual domain
Check REPL_ID is set correctly
Ensure ISSUER_URL=https://identity.util.repl.co
Clear browser cookies and try again

Database Connection Errors

Symptoms: “Connection timeout” or “Connection refused” errors Solutions:

Verify DATABASE_URL format: postgresql://user:pass@host:5432/db
Check database firewall allows Replit IP ranges
Test connection with npm run db:push
Review Neon/database provider status page

File Upload Failures

Symptoms: Manual sessions or media vault uploads fail Solutions:

Check Supabase project is not paused
Verify all three Supabase env vars are set
Test storage with GET /api/storage/status
Review Supabase Storage bucket permissions

Application Won’t Start

Symptoms: Run button fails or crashes immediately Solutions:

Check for TypeScript errors: npm run check
Review startup logs in Replit console
Verify all required env vars are set
Rebuild: npm run build
Clear Replit cache and reinstall: rm -rf node_modules && npm install

Performance Optimization

Enable Connection Pooling

For better database performance, configure connection pool settings:

DB_POOL_MAX=20
DB_POOL_MIN=2
DB_POOL_IDLE=10000
DB_CONNECT_TIMEOUT=10
DB_MAX_LIFETIME=3600

See Database Setup for details.

Monitor Resource Usage

Replit provides built-in monitoring:

Open your Repl
Click “Monitoring” in the left sidebar
Review CPU, memory, and network usage
Set up alerts for threshold breaches

Enable Always On (Paid Plans)

For production deployments, enable “Always On” to prevent automatic shutdown:

Open Repl settings
Toggle “Always On”
Your application will run 24/7 without sleeping

Security Best Practices

Never commit secrets to Git! Always use Replit Secrets for sensitive data.

Use strong SESSION_SECRET (32+ random characters)
Rotate API keys periodically
Enable Replit’s “Private” Repl setting for closed-source projects
Review Replit audit logs regularly
Keep dependencies updated: npm update
Monitor for security advisories: npm audit

Scaling Considerations

Database Scaling

Neon supports automatic scaling:

Enable autoscaling in Neon dashboard
Set compute limits based on traffic
Monitor query performance
Add read replicas for heavy read workloads

File Storage Scaling

Supabase Storage scales automatically:

Buckets have no hard file limits
CDN handles global distribution
Monitor storage quota in Supabase dashboard
Implement cleanup jobs for old files

Application Scaling

For high-traffic deployments:

Upgrade to Replit’s higher-tier plans
Enable connection pooling (see above)
Implement Redis caching for session data
Consider load balancing across multiple Repls

Next Steps

Environment Variables

Complete reference for all environment variables

Database Setup

PostgreSQL and Neon configuration guide

Storage Configuration

Supabase Storage setup and management

Architecture

Understanding JOIP’s technical architecture

Environment Variables

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Deployment

Development

Integrations

Overview

Prerequisites

Deployment Steps

Custom Domain Setup

Replit-Specific Configuration

Automatic Environment Detection

OIDC Authentication Flow

Session Management

Port Configuration

Environment Validation

Deployment Checklist

Troubleshooting

OIDC Authentication Fails

Database Connection Errors

File Upload Failures

Application Won’t Start

Performance Optimization

Enable Connection Pooling

Monitor Resource Usage

Enable Always On (Paid Plans)

Security Best Practices

Scaling Considerations

Database Scaling

File Storage Scaling

Application Scaling

Next Steps

Environment Variables

Database Setup

Storage Configuration

Architecture

Build docs developers (and LLMs) love

Deployment

Development

Integrations

​Overview

​Prerequisites

​Deployment Steps

​Custom Domain Setup

​Replit-Specific Configuration

​Automatic Environment Detection

​OIDC Authentication Flow

​Session Management

​Port Configuration

​Environment Validation

​Deployment Checklist

​Troubleshooting

​OIDC Authentication Fails

​Database Connection Errors

​File Upload Failures

​Application Won’t Start

​Performance Optimization

​Enable Connection Pooling

​Monitor Resource Usage

​Enable Always On (Paid Plans)

​Security Best Practices

​Scaling Considerations

​Database Scaling

​File Storage Scaling

​Application Scaling

​Next Steps

Environment Variables

Database Setup

Storage Configuration

Architecture

Build docs developers (and LLMs) love

Overview

Prerequisites

Deployment Steps

Custom Domain Setup

Replit-Specific Configuration

Automatic Environment Detection

OIDC Authentication Flow

Session Management

Port Configuration

Environment Validation

Deployment Checklist

Troubleshooting

OIDC Authentication Fails

Database Connection Errors

File Upload Failures

Application Won’t Start

Performance Optimization

Enable Connection Pooling

Monitor Resource Usage

Enable Always On (Paid Plans)

Security Best Practices

Scaling Considerations

Database Scaling

File Storage Scaling

Application Scaling

Next Steps