Skip to main content

​
Prerequisites

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

Docker

Required for running PostgreSQL databaseDownload Docker

Bun

Fast JavaScript runtime and package managerInstall Bun
Jefftube uses Bun for all JavaScript operations instead of Node.js or npm. Make sure you have Bun installed before proceeding.

​
Installation

Follow these steps to get Jefftube running on your local machine:
1

Clone the Repository

Start by cloning the Jefftube repository from GitHub:
git clone https://github.com/imMatheus/jefftube.git
cd jefftube
The repository contains three main directories:
  • server/ - Hono API backend
  • web/ - React frontend
  • scrapper/ - Playwright scraper (optional for local development)
2

Start the Database

Navigate to the server directory and start the PostgreSQL database using Docker Compose:
cd server
bun run db:start
This command starts a PostgreSQL 16 container with the following configuration:
  • Container name: jtube-postgres
  • Port: 5432
  • Database: jtube
  • User: jtube
  • Password: jtube
Make sure Docker Desktop is running before executing this command.
3

Set Up Database Schema

Push the database schema to your PostgreSQL instance:
bun run db:push
This creates all necessary tables:
  • videos - Video metadata and statistics
  • users - User accounts (IP-based)
  • comments - Threaded comment system
  • comment_likes - Comment reactions
  • video_likes - Video reactions
To explore your database visually, run bun run db:studio to open Drizzle Studio in your browser.
4

Install Dependencies and Start Backend

Install server dependencies and start the development server:
bun install
bun run dev
The API server will start at http://localhost:3001 with hot reload enabled.You should see output similar to:
{"level":30,"time":1234567890,"port":3001,"msg":"server running at http://localhost:3001"}
5

Start the Frontend (New Terminal)

Open a new terminal window, navigate to the web directory, and start the frontend:
cd web
bun install
bun run dev
The frontend will start at http://localhost:5173 (default Vite port).
Vite will automatically open your browser. If not, manually navigate to http://localhost:5173

​
Verify Your Installation

Once both servers are running, verify everything is working correctly:
Visit the health check endpoint to ensure the API is responding:
curl http://localhost:3001/health
Expected response:
{
  "status": "ok",
  "timestamp": "2026-03-05T12:34:56.789Z"
}
Open your browser to http://localhost:5173You should see the Jefftube interface with:
  • Navigation header with theme toggle
  • Sidebar with playlist categories
  • Main content area (may be empty without seeded data)
You can verify the database connection by fetching videos:
curl http://localhost:3001/api/videos
This returns an array of videos (empty array if no data is seeded).

​
Development Workflow

Now that you have Jefftube running, here are common development tasks:

​
Database Management

# Start the database
bun run db:start

# Stop the database
bun run db:stop

# Generate migration files
bun run db:generate

# Apply migrations
bun run db:migrate

# Open Drizzle Studio (database GUI)
bun run db:studio

# Seed the database with sample data
bun run db:seed

​
Server Commands

# Development mode with hot reload
bun run dev

# Production mode
bun run start

# Run database queries
bun run db:query

​
Frontend Commands

# Development mode
bun run dev

# Build for production
bun run build

# Preview production build
bun run preview

# Run ESLint
bun run lint

​
Environment Variables

The application uses sensible defaults, but you can customize behavior with environment variables: 
# Database connection
DATABASE_URL=postgres://jtube:jtube@localhost:5432/jtube

# Server port
PORT=3001
The application will work without these environment variables using defaults. Only create .env files if you need to override default values.

​
Common Issues

If port 3001 or 5173 is already in use:For the API server:
PORT=3002 bun run dev
For the frontend: Update vite.config.ts or use:
bun run dev -- --port 5174
If you see database connection errors:
  1. Verify Docker is running: docker ps
  2. Check the container is up: docker ps | grep jtube-postgres
  3. Restart the database: bun run db:stop && bun run db:start
  4. Verify the connection string in server/src/db/index.ts
If you encounter missing module errors:
# Clean install dependencies
rm -rf node_modules
bun install

​
Next Steps

Now that you have Jefftube running locally, explore these resources:

Architecture Guide

Understand the full-stack architecture and design decisions

Database Schema

Explore table structures and relationships

API Reference

Learn about available endpoints and data models

Core Features

Deep dive into video browsing, comments, and playlists

​
Need Help?

GitHub Repository

Found a bug or have questions? Check out the GitHub repository for issues and discussions.

Build docs developers (and LLMs) love

Get started for freeTalk to us