Skip to main content
Get your JOIP Web Application up and running in under 10 minutes. This guide walks you through installation, configuration, and creating your first session.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 20+ installed
  • PostgreSQL database (local or cloud)
  • Reddit API credentials (Get them here)
  • Supabase account for file storage (Sign up)

​
Quick installation

1

Clone and install

git clone https://github.com/MatthewSabia1/Joip-Web-App-2.git
cd Joip-Web-App-2
npm install
2

Configure environment

Create a .env file in the project root:
# Database
DATABASE_URL="postgresql://user:password@localhost:5432/joip"

# Session
SESSION_SECRET="your-secure-random-string-here"

# Reddit API
REDDIT_CLIENT_ID="your-reddit-client-id"
REDDIT_CLIENT_SECRET="your-reddit-client-secret"

# Supabase Storage
SUPABASE_URL="https://your-project.supabase.co"
SUPABASE_ANON_KEY="your-anon-key"
SUPABASE_SERVICE_KEY="your-service-key"
See the Environment Setup guide for complete configuration options.
3

Initialize database

Apply database migrations:
npm run db:push
This creates all necessary tables and relationships.
4

Start development server

npm run dev
The application will start on http://localhost:5000
5

Create your account

  • Navigate to http://localhost:5000
  • Click Sign Up or Login
  • Create a local development account
  • Complete the age verification (18+)

​
Create your first session

Now that you’re set up, let’s create a multimedia session with AI-generated captions.

​
Reddit-based session

1

Navigate to Sessions

Click Sessions in the sidebar, then click New Session → Reddit Session
2

Configure your session

Fill in the session details:
  • Title: My First JOIP Session
  • Subreddits: pics, aww (comma-separated)
  • Interval: 5-10 seconds (how long each image displays)
  • Transition: Fade
  • Caption Theme: JOI (or choose your preference)
3

Save and play

  1. Click Save Session
  2. Wait for media to populate (happens automatically)
  3. Click Play to start the slideshow
Your first session may take 10-15 seconds to fetch media from Reddit and generate AI captions.

​
Manual session

Prefer to upload your own images? Create a custom session:
1

Start manual session

Click Sessions → New Session → Manual Session
2

Upload images

  • Drag and drop images, or click to browse
  • Paste images from clipboard
  • Add up to 100 images (100MB each max)
3

Write captions

For each slide, write your custom caption (no character limit, but keep under 500 for best display)
4

Configure and save

  • Set your intervals and transition
  • Choose a thumbnail
  • Click Create Session

​
Enable AI features (Optional)

To use AI caption generation and Smart Captions, add AI provider keys:
Without AI provider keys, caption generation will fall back to themed templates.

​
Explore features

Now that you have your first session, explore these features:

Smart Captions

Generate AI captions for any image with customizable themes and styling

Babecock Studio

Combine images with automatic layout detection

Media Vault

Manage your uploaded files in a centralized library

Community

Discover and share sessions with the community

​
Common issues

Cause: Invalid DATABASE_URL or database not runningSolution:
  1. Verify your database is running: pg_isready
  2. Check connection string format: postgresql://user:password@host:5432/database
  3. Ensure database exists: createdb joip
Cause: Invalid Reddit credentialsSolution:
  1. Verify credentials at reddit.com/prefs/apps
  2. Ensure you’re using the correct client ID and secret
  3. Check that your app type is “web app” or “script”
Cause: Supabase Storage not configured or credentials invalidSolution:
  1. Verify Supabase project URL and keys
  2. Create user-media and general buckets in Supabase
  3. Set bucket policies to public
  4. Check storage diagnostics: GET /api/storage/status
Cause: Missing AI provider keys or content policy rejectionSolution:
  1. Add OPENROUTER_API_KEY or OPENAI_API_KEY to .env
  2. Restart the server
  3. Check server logs for API errors
  4. Try a different caption theme

​
Next steps

Installation Guide

Complete installation instructions for all environments

Environment Setup

Comprehensive environment variable reference

API Documentation

Explore the REST API for programmatic access

Deployment Guide

Deploy to Replit for production use

Build docs developers (and LLMs) love

Get started for freeTalk to us