Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:
1

Install Bun

Jefftube uses Bun as the JavaScript runtime and package manager.
curl -fsSL https://bun.sh/install | bash
Verify installation:
bun --version
2

Install Docker

Docker is required to run the PostgreSQL database.Download and install Docker Desktop for your operating system.Verify installation:
docker --version
docker compose version
3

Install Git

git --version
If not installed, download from git-scm.com

​
Project Structure

Jefftube is organized as a monorepo with three main components: 
source/
├── web/          # React frontend (Vite + React 19)
├── server/       # Hono backend (Bun + PostgreSQL)
└── scrapper/     # Playwright scraper

​
Clone the Repository

git clone <repository-url>
cd source

​
Backend Setup (Server)

1

Navigate to server directory

cd server
2

Install dependencies

bun install
3

Start PostgreSQL database

The server uses Docker Compose to run PostgreSQL 16.
bun run db:start
This will start a PostgreSQL container with:
  • User: jtube
  • Password: jtube
  • Database: jtube
  • Port: 5432
4

Run database migrations

Apply the database schema using Drizzle Kit:
bun run db:push
5

Seed the database (optional)

Populate the database with initial video data:
bun run db:seed
The seed script filters out videos with null titles and NSFW content from src/data.json and src/video-state.json.
6

Start the development server

bun run dev
The server will start on http://localhost:3001 with hot reload enabled.

​
Server Environment Variables

The server uses the following environment variables (all optional with defaults):
VariableDefaultDescription
PORT3001Server port
DATABASE_URLpostgres://jtube:jtube@localhost:5432/jtubePostgreSQL connection string
NODE_ENV(none)Set to production to disable debug logging
RECAPTCHA_SECRET_KEY(none)Google reCAPTCHA v3 secret key for verification. If not set, reCAPTCHA checks are skipped

​
Frontend Setup (Web)

1

Navigate to web directory

cd web
2

Install dependencies

bun install
3

Create environment file

Copy the example environment file:
cp .env.example .env
Edit .env with your configuration:
VITE_API_URL=http://localhost:3001
VITE_PUBLIC_POSTHOG_KEY=your_posthog_project_api_key
VITE_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com
VITE_RECAPTCHA_SITE_KEY=your_recaptcha_v3_site_key
All variables are optional. PostHog and reCAPTCHA are not required for local development. VITE_API_URL defaults to the production API if not set.
4

Start the development server

bun run dev
The frontend will start on http://localhost:5173 (default Vite port) with hot module replacement.

​
Frontend Environment Variables

VariableDefaultDescriptionRequired
VITE_API_URLhttps://jefftube-server-758971609529.us-central1.run.appBackend API URLNo
VITE_PUBLIC_POSTHOG_KEY(hardcoded fallback)PostHog analytics project API keyNo
VITE_PUBLIC_POSTHOG_HOSThttps://us.i.posthog.comPostHog host URLNo
VITE_RECAPTCHA_SITE_KEY(hardcoded fallback)Google reCAPTCHA v3 site keyNo

​
Scraper Setup (Scrapper)

The scraper extracts video metadata from the Department of Justice Epstein disclosures.
1

Navigate to scrapper directory

cd scrapper
2

Install dependencies

bun install
This will install Playwright and its browser dependencies.
3

Install Playwright browsers

bunx playwright install chromium
4

Run the scraper

bun run scrape
Available scraping options:
# Scrape specific dataset (9, 10, or 11)
bun run scrape:9
bun run scrape:10
bun run scrape:11

# Run with visible browser (for debugging)
bun run scrape:visible

# Test scrape (limit to 50 pages)
bun run scrape:test

# Fast scrape (20 concurrent pages)
bun run scrape:fast

# Retry failed pages
bun run scrape:retry

# Clear progress and start fresh
bun run scrape:fresh

​
Running the Full Stack

To run the complete application: 
cd server
bun run db:start  # Start database (first time only)
bun run dev       # Start backend server
Access the application at:

​
Available Scripts

​
Backend Scripts

CommandDescription
bun run devStart development server with hot reload
bun run startStart production server
bun run db:startStart PostgreSQL with Docker
bun run db:stopStop PostgreSQL container
bun run db:generateGenerate migration files
bun run db:migrateRun migrations
bun run db:pushPush schema changes to database
bun run db:studioOpen Drizzle Studio (database GUI)
bun run db:seedSeed database with video data

​
Frontend Scripts

CommandDescription
bun run devStart Vite dev server
bun run buildBuild for production
bun run previewPreview production build
bun run lintRun ESLint
bun run startServe production build

​
Troubleshooting

Problem: Cannot connect to PostgreSQL database.Solutions:
  1. Ensure Docker is running: docker ps
  2. Check if the database container is running: docker ps | grep jtube-postgres
  3. Restart the database: bun run db:stop && bun run db:start
  4. Verify the DATABASE_URL environment variable matches your setup
Problem: Port 3001 or 5173 is already in use.Solutions:
  1. Find and kill the process using the port: 
    # Linux/Mac
lsof -ti:3001 | xargs kill -9
lsof -ti:5173 | xargs kill -9
  2. Or change the port:
    • Backend: Set PORT environment variable
    • Frontend: Edit vite.config.ts to add server: { port: 5174 }
Problem: Import errors or missing dependencies.Solutions:
  1. Clear Bun cache: rm -rf node_modules && bun install
  2. Ensure you’re using Bun (not npm/yarn): bun --version
  3. Check that you’re in the correct directory (web/ or server/)
Problem: Database migrations fail or schema mismatch.Solutions:
  1. Reset the database: 
    bun run db:stop
docker volume rm server_postgres_data
bun run db:start
bun run db:push
  2. Regenerate migrations: bun run db:generate
Problem: Scraper blocked by “I am not a robot” check.Solutions:
  1. Reduce concurrency: bun run scraper.ts --concurrency 3
  2. Run in visible mode to see what’s happening: bun run scrape:visible
  3. Add delays between requests (edit STAGGER_DELAY_MS in scraper.ts)

​
Next Steps

Architecture

Understand the system architecture and how components interact

Database Schema

Learn about the database structure and relationships

Build docs developers (and LLMs) love

Get started for freeTalk to us