1 Getting-Started

xpltd_admin edited this page 2026-04-03 22:39:32 -06:00

Table of Contents

• Getting Started
• Prerequisites
• Local Development Setup
• 1. Clone the repository
• 2. Install dependencies
• 3. Create environment file
• 4. Run database migrations
• 5. Start the development server
• 6. (Optional) Run frontend separately
• Docker Setup
• Quick start with Docker Compose
• Custom compose configuration
• Environment Variables
• Common Commands
• Troubleshooting
• yt-dlp not found
• Database locked errors
• Port already in use
• ffmpeg not found
• Frontend not loading (development)
• API key lost

Getting Started

Meta	Value
Repo	xpltdco/tubearr
Page	Getting-Started
Audience	developers, newcomers
Last Updated	2026-04-04
Status	current

Prerequisites

Requirement	Version	Purpose
Node.js	>= 18.0.0	Runtime
npm	>= 9	Package management
yt-dlp	Latest	Media downloading (install via pip install yt-dlp or your package manager)
ffmpeg	Any recent	Media transcoding and post-processing
Python 3	>= 3.8	Required by yt-dlp

Docker shortcut: If you just want to run it, skip to Docker Setup — everything is bundled in the image.

Local Development Setup

1. Clone the repository

git clone https://git.xpltd.co/xpltdco/tubearr.git
cd tubearr

2. Install dependencies

npm install

3. Create environment file

cp .env.example .env

Edit .env as needed. The defaults work for local development:

TUBEARR_PORT=8989
TUBEARR_DB_PATH=./data/tubearr.db
TUBEARR_LOG_LEVEL=info
NODE_ENV=development

4. Run database migrations

npm run db:migrate

This creates the SQLite database at the configured TUBEARR_DB_PATH and applies all schema migrations.

5. Start the development server

npm run dev

This starts the Fastify backend with tsx watch (auto-reload on file changes). The frontend Vite dev server runs on the same port via middleware, so you get full HMR.

Open http://localhost:8989 in your browser.

First run note: Tubearr generates an API key on first startup and logs it to stdout once. You'll see a line like API Key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Save this if you need to make external API calls.

6. (Optional) Run frontend separately

If you prefer running the Vite dev server standalone:

npm run dev:frontend

This runs Vite on its own port with HMR. API requests proxy to the backend on port 8989.

Docker Setup

Quick start with Docker Compose

docker compose up -d

This builds the image and starts the container with:

• Port 8989 exposed
• Named volume tubearr-config for database and cookies
• Bind mount ./media for downloaded files

Custom compose configuration

services:
  tubearr:
    build: .
    container_name: tubearr
    ports:
      - "8989:8989"
    volumes:
      - tubearr-config:/config
      - /path/to/your/media:/media    # Change this to your media directory
    environment:
      - NODE_ENV=production
      - TUBEARR_PORT=8989
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:8989/ping"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
    restart: unless-stopped

volumes:
  tubearr-config:

Environment Variables

See the full Configuration page for all variables. The essentials:

Variable	Default	Purpose
TUBEARR_PORT	8989	Server listen port
TUBEARR_DB_PATH	./data/tubearr.db	SQLite database location
TUBEARR_MEDIA_PATH	./media	Where downloaded files are stored
TUBEARR_LOG_LEVEL	info	Log verbosity (trace/debug/info/warn/error/fatal)
NODE_ENV	development	Set to production for Docker deployments

Common Commands

Command	Purpose
npm run dev	Start dev server with hot reload
npm run dev:frontend	Start Vite frontend dev server separately
npm run build	Compile TypeScript backend to dist/
npm run build:frontend	Build React SPA to dist/frontend/
npm start	Run compiled server (production)
npm test	Run Vitest test suite
npm run db:generate	Generate migration from schema changes
npm run db:migrate	Apply pending migrations

Troubleshooting

yt-dlp not found

If you see errors about yt-dlp not being available:

• Local dev: Install it globally: pip install yt-dlp or brew install yt-dlp
• Docker: It's bundled in the image — this shouldn't happen. Check that the Dockerfile build completed successfully.

Database locked errors

SQLite WAL mode handles most concurrency, but if you see "database is locked":

• Ensure only one instance of Tubearr is accessing the database file
• Check that PRAGMA busy_timeout = 5000 is being set (it is by default)

Port already in use

Change TUBEARR_PORT in your .env file, or stop whatever is using port 8989:

lsof -i :8989

ffmpeg not found

Downloads may complete but post-processing (format conversion, subtitle embedding) will fail. Install ffmpeg:

• macOS: brew install ffmpeg
• Linux: apt install ffmpeg or apk add ffmpeg
• Docker: It's bundled in the image.

Frontend not loading (development)

If you see a blank page in dev mode:

• Make sure you ran npm install (Vite and React deps are needed)
• Check that NODE_ENV is set to development (not production) — this enables Vite middleware
• Look for errors in the terminal where npm run dev is running

API key lost

If you forgot the auto-generated API key:

• Check the system_config table: the key is stored with key api_key
• Or regenerate via the Settings page in the UI
• Or use the API: POST /api/v1/system/apikey/regenerate