Installation

Complete installation guide for JOIP - local development and production deployment

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

Local Development Setup

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

1. Clone Repository

   git clone <your-repo-url>
   cd <your-repo-name>
   
2. 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.

3. 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:

   1. Sign up at https://supabase.com
   2. Create a new project
   3. Go to Settings → Database
   4. Copy the connection string (URI format)
   5. 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:

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

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

4. 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
   
5. 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.

6. 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 Production

Replit Deployment

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

1. Import to Replit

   1. Go to https://replit.com
   2. Click “Create Repl”
   3. Choose “Import from GitHub”
   4. Enter your repository URL
   5. Select Node.js as the language
2. Configure Environment Variables

   In the Replit Secrets tab, add:

   Required Secrets

   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.

3. 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"
   
4. Run Database Migrations

   In the Replit Shell, run:

   npm run db:push
   
5. 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

Docker Deployment

For containerized deployments with Docker or Docker Compose.

1. 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"]
   
2. 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:
   
3. 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:

1. Create Reddit App

   1. Go to https://www.reddit.com/prefs/apps
   2. Click “Create App” or “Create Another App”
   3. Choose “script” for personal use
   4. Fill in app details:
      • Name: “JOIP Local Dev”
      • Redirect URI: http://localhost:5000/callback
2. 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:

1. Sign Up

   Create an account at https://openrouter.ai

2. Generate API Key

   1. Navigate to Settings → API Keys
   2. Click “Create API Key”
   3. Copy the key (starts with sk-or-v1-)
3. 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:

1. Create Supabase Project

   1. Sign up at https://supabase.com
   2. Click “New Project”
   3. Choose organization and set project details
2. Get API Credentials

   1. Go to Settings → API
   2. Copy:
      • Project URL
      • anon public key
      • service_role key (keep secret!)
3. Configure Environment

   SUPABASE_URL="https://your-project.supabase.co"
   SUPABASE_ANON_KEY="your_anon_public_key"
   SUPABASE_SERVICE_KEY="your_service_role_key"
   
4. 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

1. Run Production Build

   npm run build
   

   This executes:

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

   Check that these exist:

   dist/
   ├── public/          # Client bundle
   │   ├── index.html
   │   ├── assets/      # JS, CSS, images
   └── index.js         # Server bundle
   
3. 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

Development

# Start dev server with HMR
npm run dev

# Type checking (no build)
npm run check

Troubleshooting

Module Not Found Errors

Symptom: Cannot find module errors during startup

Solution:

# 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 errors

Solution:

• 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 errors

Solution:

# 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 errors

Solution:

1. Verify Supabase credentials in .env
2. Check if project is paused (resume in Supabase dashboard)
3. Test storage status:
   curl http://localhost:5000/api/storage/status
   
4. 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

1. Environment Security

   • Never commit .env files to Git
   • Use strong SESSION_SECRET (32+ characters)
   • Rotate API keys regularly
   • Use environment-specific API keys
2. Database Security

   • Use strong database passwords
   • Enable SSL for database connections
   • Restrict database IP whitelist
   • Regular backup schedule
3. Application Security

   • Keep dependencies updated
   • Enable rate limiting in production
   • Configure CORS properly
   • Use HTTPS in production

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

Next Steps

Environment Setup

Complete guide to all environment variables and configuration options

Quick Start

Create your first session and explore features