Installation

System Requirements

Runtime

Node.js: 18+ (LTS recommended)
npm: Latest version
PostgreSQL: 13+ or compatible cloud service

Development

Git: For version control
Code Editor: VSCode, Cursor, or similar
Terminal: Bash, Zsh, or PowerShell

Installation Methods

Local Development
Replit Production
Docker

Local Development Setup

Perfect for development on your local machine with full control over all components.

Clone Repository

git clone <your-repo-url>
cd <your-repo-name>

Install Dependencies

npm install

This installs all required packages:

React 18 with TypeScript
Express.js with TypeScript
Drizzle ORM for database operations
Tailwind CSS + Radix UI for styling
TanStack React Query for state management
Sharp for image processing
And 100+ other dependencies

Installation may take 2-5 minutes depending on your connection speed.

Database Setup

Choose one of these PostgreSQL options:

Option A: Local PostgreSQL

Install PostgreSQL on your machine:

# macOS (via Homebrew)
brew install postgresql@15
brew services start postgresql@15

# Ubuntu/Debian
sudo apt-get install postgresql-15
sudo systemctl start postgresql

# Create database
createdb joip_dev

Set your DATABASE_URL:

DATABASE_URL="postgresql://postgres:password@localhost:5432/joip_dev"

Option B: Supabase (Recommended)

Free cloud PostgreSQL with storage included:

Sign up at https://supabase.com
Create a new project
Go to Settings → Database
Copy the connection string (URI format)
Paste into .env as DATABASE_URL

Supabase provides both database AND storage, making it the recommended option.

Option C: Neon

Serverless PostgreSQL with generous free tier:

Sign up at https://neon.tech
Create a new project
Copy the connection string
Add to .env as DATABASE_URL

Neon is optimized for serverless deployments and has excellent cold start performance.

Environment Configuration

Copy the example environment file:

cp .env.example .env

Edit .env with required values:

# Database (required)
DATABASE_URL="postgresql://username:password@host:5432/database"

# Session Security (required)
SESSION_SECRET="generated-with-openssl-rand-hex-32"

# Application Settings
NODE_ENV="development"
PORT=5000

Generate a secure session secret:

openssl rand -hex 32

Apply Database Migrations

Create all required database tables:

npm run db:push

This creates:

users - User profiles and authentication
content_sessions - Session configurations
session_media - Media items within sessions
user_media - Personal media vault
shared_sessions - Public sharing codes
community_sessions - Community feed snapshots
user_usage_stats - Analytics and tracking
And 10+ more tables with comprehensive constraints

The schema includes 36 total constraints including foreign keys, unique constraints, and indexes for data integrity.

Start Development Server

npm run dev

The server will start on http://localhost:5000 with:

Vite HMR on port 5173 (auto-proxied)
API routes under /api
Client application served at root

The development server includes hot module replacement (HMR) for instant updates during development.

Verify Installation

Check Server Logs

You should see output like:

✓ Database connected successfully
✓ Connection pool initialized
✓ Vite dev server started
✓ Server listening on port 5000

Test Database Connection

Visit http://localhost:5000 and try logging in. The local auth strategy allows any credentials in development.

Replit Deployment

JOIP is designed for seamless deployment on Replit with production-ready configuration.

Import to Replit

Go to https://replit.com
Click “Create Repl”
Choose “Import from GitHub”
Enter your repository URL
Select Node.js as the language

Configure Environment Variables

In the Replit Secrets tab, add:

DATABASE_URL="postgresql://user:pass@host:5432/db"
SESSION_SECRET="your-secure-random-string"

# Replit OAuth (auto-populated)
REPLIT_DOMAINS="your-repl.replit.app"
REPL_ID="your-repl-id"
ISSUER_URL="https://replit.com/oidc"

# Application
NODE_ENV="production"

Replit automatically sets REPLIT_DOMAINS, REPL_ID, and other platform variables.

Add API Keys

Configure optional services in Secrets:

# Reddit Integration
REDDIT_CLIENT_ID="your_client_id"
REDDIT_CLIENT_SECRET="your_client_secret"

# AI Services
OPENROUTER_API_KEY="sk-or-v1-your_key"
XAI_API_KEY="xai-your_key"
FREEPIK_API_KEY="your_freepik_key"

# Cloud Storage
SUPABASE_URL="https://project.supabase.co"
SUPABASE_ANON_KEY="your_anon_key"
SUPABASE_SERVICE_KEY="your_service_key"

Run Database Migrations

In the Replit Shell, run:

npm run db:push

Start Production Server

Click “Run” or execute:

npm run build
npm start

The app will be available at your Replit URL.

Replit-Specific Features

OAuth Integration

Automatic Replit OIDC authentication when REPLIT_DOMAINS is detected

Always-On

Configure Replit’s “Always On” feature for 24/7 availability

Auto-Deploy

Connect to GitHub for automatic deployments on push

Resource Monitoring

Built-in monitoring for CPU, memory, and database connections

Docker Deployment

For containerized deployments with Docker or Docker Compose.

Create Dockerfile

Create Dockerfile in project root:

FROM node:18-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production

# Copy application files
COPY . .

# Build application
RUN npm run build

# Expose port
EXPOSE 5000

# Start server
CMD ["npm", "start"]

Create Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "5000:5000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/joip
      - SESSION_SECRET=${SESSION_SECRET}
      - NODE_ENV=production
    depends_on:
      - db

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=joip
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

Build and Run

# Build containers
docker-compose build

# Start services
docker-compose up -d

# Run migrations
docker-compose exec app npm run db:push

# View logs
docker-compose logs -f

Post-Installation Setup

Configure API Integrations

Reddit API Setup

Required for Reddit-based sessions:

Create Reddit App

Go to https://www.reddit.com/prefs/apps
Click “Create App” or “Create Another App”
Choose “script” for personal use
Fill in app details:
- Name: “JOIP Local Dev”
- Redirect URI: http://localhost:5000/callback

Add Credentials

Copy the client ID and secret to .env:

REDDIT_CLIENT_ID="your_client_id_here"
REDDIT_CLIENT_SECRET="your_client_secret_here"

OpenRouter AI Setup

Recommended for AI caption generation:

Create an account at https://openrouter.ai

Generate API Key

Navigate to Settings → API Keys
Click “Create API Key”
Copy the key (starts with sk-or-v1-)

Add to Environment

OPENROUTER_API_KEY="sk-or-v1-your_key_here"

The app uses Gemini family models via OpenRouter:

Manual Editor: google/gemini-2.5-pro (fallback: gemini-2.5-flash-lite)
Smart Captions: gemini-2.5-flash-lite

Supabase Storage Setup

Required for manual sessions and Media Vault:

Create Supabase Project

Sign up at https://supabase.com
Click “New Project”
Choose organization and set project details

Get API Credentials

Go to Settings → API
Copy:
- Project URL
- anon public key
- service_role key (keep secret!)

Configure Environment

SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_ANON_KEY="your_anon_public_key"
SUPABASE_SERVICE_KEY="your_service_role_key"

Create Storage Buckets

The app automatically creates required buckets:

user-media: User uploads and manual sessions
general: Community content and shared media

Buckets are created automatically on first upload if they don’t exist.

AI Image Services

Optional for AI Undress feature:xAI (Primary Provider):

XAI_API_KEY="xai-your_key_here"
XAI_UNDRESS_MODEL="grok-imagine-image-pro"  # Optional override

Freepik (Fallback Provider):

FREEPIK_API_KEY="your_freepik_key_here"

Provider Selection:

UNDRESS_PRIMARY_PROVIDER="xai"  # or "freepik"

Build for Production

Run Production Build

npm run build

This executes:

Logo Generation: node scripts/generate-logos.mjs
Client Build: vite build → outputs to dist/public
Server Build: esbuild → outputs to dist/index.js
- Platform: Node.js
- Format: ESM
- Minified with tree-shaking

Verify Build Output

Check that these exist:

dist/
├── public/          # Client bundle
│   ├── index.html
│   ├── assets/      # JS, CSS, images
└── index.js         # Server bundle

Start Production Server

NODE_ENV=production npm start

The server:

Serves static files from dist/public
Handles API routes under /api
Listens on port 5000 (or PORT env var)

NPM Scripts Reference

# Start dev server with HMR
npm run dev

# Type checking (no build)
npm run check

# Apply schema changes (Drizzle)
npm run db:push

# Build client + server
npm run build

# Build app only (alias)
npm run build:app

# Start production server
npm start

Troubleshooting

Module Not Found Errors

Symptom: Cannot find module errors during startupSolution:

# Clean install
rm -rf node_modules package-lock.json
npm install

# Verify Node version
node --version  # Should be 18+

Database Connection Failed

Symptom: “Connection refused” or timeout errorsSolution:

Verify DATABASE_URL is correctly formatted

For local PostgreSQL: Check if service is running

# macOS
brew services list

# Linux
sudo systemctl status postgresql

For cloud database: Verify firewall allows your IP
Test connection:
psql "$DATABASE_URL"

Build Failures

Symptom: Build process fails with errorsSolution:

# Clear build cache
rm -rf dist/

# Ensure TypeScript has no errors
npm run check

# Rebuild
npm run build

Port Already in Use

Symptom: “Port 5000 is already in use”Solution:

# Option 1: Change port in .env
PORT=3000

# Option 2: Find and kill process
lsof -ti:5000 | xargs kill -9

Supabase Storage Issues

Symptom: Manual sessions fail with 503 errorsSolution:

Verify Supabase credentials in .env
Check if project is paused (resume in Supabase dashboard)

Test storage status:

curl http://localhost:5000/api/storage/status

Review error codes:
- STORAGE_CONFIG_ERROR: Missing env variables
- STORAGE_UNREACHABLE: Cannot connect to Supabase
- STORAGE_PREFLIGHT_FAILED: Bucket test failed

Health Checks

Verify your installation with these endpoints:

# Basic health check
curl http://localhost:5000/api/health

# Storage diagnostics
curl http://localhost:5000/api/storage/status

# Database connection health
curl http://localhost:5000/api/health/database

Performance Optimization

Database

Connection pooling enabled by default
Health monitoring with retry logic
Indexes on all foreign keys
Query timeout: 20 seconds

Application

Production build minified
Tree-shaking enabled
Static asset caching
Image optimization with Sharp

Security Checklist

Never expose API keys or secrets in client code. All sensitive operations should go through server-side API routes.

Getting Started

Core Features

Content Tools

User Management

Administration

System Requirements

Runtime

Development

Installation Methods

Local Development Setup

Verify Installation

Replit Deployment

Replit-Specific Features

OAuth Integration

Always-On

Auto-Deploy

Resource Monitoring

Docker Deployment

Post-Installation Setup

Configure API Integrations

Build for Production

NPM Scripts Reference

Troubleshooting

Health Checks

Performance Optimization

Database

Application

Security Checklist

Next Steps

Environment Setup

Quick Start

​System Requirements

Runtime

Development

​Installation Methods

​Local Development Setup

​Verify Installation

​Replit Deployment

​Replit-Specific Features

OAuth Integration

Always-On

Auto-Deploy

Resource Monitoring

​Docker Deployment

​Post-Installation Setup

​Configure API Integrations

​Build for Production

​NPM Scripts Reference

​Troubleshooting

​Health Checks

​Performance Optimization

Database

Application

​Security Checklist

​Next Steps

Environment Setup

Quick Start

System Requirements

Installation Methods

Local Development Setup

Verify Installation

Replit Deployment

Replit-Specific Features

Docker Deployment

Post-Installation Setup

Configure API Integrations

Build for Production

NPM Scripts Reference

Troubleshooting

Health Checks

Performance Optimization

Security Checklist

Next Steps