Skip to main content
Get TikTok Miner up and running quickly. This guide will take you from installation to your first creator search in just a few steps.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18.x or higher
  • Bun 1.2.5 or higher (recommended) or npm/yarn/pnpm
  • PostgreSQL 14 or higher
  • Redis 7 or higher (for job queues)
  • A TikTok API key or Apify account (for scraping)

​
Quick Start with Docker

The fastest way to get started is using Docker Compose:
1

Clone and Configure

Clone the repository and set up your environment:
git clone <repository-url>
cd tiktok-miner/app
cp .env.example .env
Edit .env and configure your credentials:
# Required: Database password
DB_PASSWORD=your_secure_password

# Required: Redis password
REDIS_PASSWORD=your_redis_password

# Required: API Keys
OPENAI_API_KEY=sk-...
GITHUB_TOKEN=ghp_...
2

Start Services

Launch all services with Docker Compose:
docker-compose up -d
This will start:
  • PostgreSQL database (port 5432)
  • Redis queue (port 6379)
  • TikTok Miner app (port 3000)
  • Discovery pipeline worker
The first startup may take a few minutes to build the containers and run database migrations.
3

Verify Installation

Check that all services are running:
docker-compose ps
You should see all services with status “Up”. Access the web interface at:
http://localhost:3000
4

Run Your First Search

Open the TikTok Miner interface and navigate to the Scraper page.
  1. Enter keywords (one per line): 
    tech
coding
programming
  2. Click “Run Pipeline”
  3. Watch the real-time terminal output as TikTok Miner:
    • Discovers creator profiles
    • Scrapes 30-day engagement metrics
    • Calculates engagement rates
    • Stores results in the database
The pipeline typically takes 2-5 minutes per keyword depending on the number of creators found.

​
Quick Start with Local Installation

Prefer to run locally? Follow these steps:
1

Install Dependencies

Using Bun (recommended):
bun install
Or with npm:
npm install
2

Configure Environment

Copy the example environment file:
cp .env.example .env
Update the following required variables:
.env
# Database (Supabase or local PostgreSQL)
DATABASE_URL="postgresql://postgres:password@localhost:5432/tiktok_miner?pgbouncer=true&connection_limit=1"
DIRECT_URL="postgresql://postgres:password@localhost:5432/tiktok_miner"

# Supabase Auth (required for authentication)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# OpenAI (required for AI features)
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o

# GitHub (optional, for extended features)
GITHUB_TOKEN=ghp_...
3

Set Up Database

Generate Prisma client and run migrations:
bun x prisma generate
bun x prisma migrate deploy
Or with npm:
npx prisma generate
npx prisma migrate deploy
Make sure PostgreSQL is running and accessible with the credentials in your DATABASE_URL.
4

Start Development Server

Launch the development server:
bun run dev
Or with npm:
npm run dev
The app will be available at http://localhost:3000
5

Run Your First Creator Search

  1. Open http://localhost:3000 in your browser
  2. Navigate to “Scraper” in the sidebar
  3. Enter keywords to search for creators: 
    fitness
cooking
travel
  4. Click “Run Pipeline” and watch the progress
  5. View discovered creators in the “Creators” tab

​
Understanding the Results

After your first search completes, you’ll see creators with:
  • Profile Information: Username, nickname, bio, follower count
  • 30-Day Metrics: Posts, total likes, comments, views, shares
  • Engagement Rate: Calculated as (likes + comments) / (views * followers)
  • Average Performance: Average likes, comments, views per post

​
Next Steps

Analytics Dashboard

Learn how to filter, sort, and analyze discovered creators

Discovery Pipeline

Deep dive into how the discovery pipeline works

API Reference

Integrate TikTok Miner into your applications

CLI Tools

Use command-line tools for automation

​
Troubleshooting

Check that:
  • PostgreSQL is running
  • DATABASE_URL and DIRECT_URL are correctly formatted
  • Database user has proper permissions
  • Port 5432 is not blocked by firewall
Test connection:
bun x prisma db pull
Verify:
  • Redis is running (if using job queues)
  • All required API keys are set
  • Network connectivity to TikTok/Apify
Check logs:
docker-compose logs app
Try:
  • Using more specific keywords
  • Checking if keywords exist on TikTok
  • Verifying API rate limits haven’t been exceeded
  • Using different keyword variations
Ensure:
  • NEXT_PUBLIC_SUPABASE_URL is set correctly
  • NEXT_PUBLIC_SUPABASE_ANON_KEY is valid
  • Supabase project is active
  • NEXT_PUBLIC_APP_URL matches your domain

​
Need Help?

If you encounter issues:

Build docs developers (and LLMs) love

Get started for freeTalk to us