Create Getting-Started wiki page with setup instructions and troubleshooting

Getting-Started.-.md

@@ -0,0 +1,189 @@
+# 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](#docker-setup) — everything is bundled in the image.
+
+## Local Development Setup
+
+### 1. Clone the repository
+
+```bash
+git clone https://git.xpltd.co/xpltdco/tubearr.git
+cd tubearr
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+### 3. Create environment file
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` as needed. The defaults work for local development:
+
+```env
+TUBEARR_PORT=8989
+TUBEARR_DB_PATH=./data/tubearr.db
+TUBEARR_LOG_LEVEL=info
+NODE_ENV=development
+```
+
+### 4. Run database migrations
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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
+
+```bash
+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
+
+```yaml
+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](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:
+
+```bash
+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`