initial commit

docs/configuration.md

@@ -0,0 +1,158 @@
+# Configuration Guide
+
+## Environment Variables
+
+Downlink uses environment variables for configuration. Create a `.env.local` file in the project root (this file is gitignored and won't be committed).
+
+### Required Configuration
+
+#### YT_DLP_PATH
+**Required if yt-dlp is not in your system PATH**
+
+Full path to the yt-dlp executable.
+
+```bash
+YT_DLP_PATH=/Users/jeff/Desktop/yt-dlp_macos
+```
+
+**When to set this:**
+- yt-dlp is not installed via package manager (brew, pip, etc.)
+- yt-dlp is in a custom location
+- You're using a standalone yt-dlp binary
+
+**How to find your yt-dlp path:**
+```bash
+# If installed via brew
+which yt-dlp
+# Output: /opt/homebrew/bin/yt-dlp
+
+# If installed via pip
+which yt-dlp
+# Output: /usr/local/bin/yt-dlp
+
+# If using standalone binary
+# Use the full path to the binary file
+```
+
+### Optional Configuration
+
+#### FFMPEG_PATH
+**Optional - Reserved for future use**
+
+Full path to ffmpeg executable (currently not used, but reserved for future configuration).
+
+```bash
+FFMPEG_PATH=/usr/local/bin/ffmpeg
+```
+
+## Configuration Examples
+
+### Example 1: yt-dlp in Custom Location
+```bash
+# .env.local
+YT_DLP_PATH=/Users/jeff/Desktop/yt-dlp_macos
+```
+
+### Example 2: yt-dlp Installed via Homebrew
+```bash
+# .env.local
+# Can be left empty if yt-dlp is in PATH
+# Or explicitly set:
+YT_DLP_PATH=/opt/homebrew/bin/yt-dlp
+```
+
+### Example 3: yt-dlp Installed via pip
+```bash
+# .env.local
+YT_DLP_PATH=/usr/local/bin/yt-dlp
+```
+
+## Environment File Setup
+
+1. **Copy the example file:**
+   ```bash
+   cp .env.example .env.local
+   ```
+
+2. **Edit `.env.local` with your configuration:**
+   ```bash
+   YT_DLP_PATH=/path/to/your/yt-dlp
+   ```
+
+3. **Restart the development server:**
+   ```bash
+   npm run dev
+   ```
+
+## Troubleshooting
+
+### yt-dlp not found error
+If you see `yt-dlp: command not found`:
+
+1. **Check if yt-dlp exists:**
+   ```bash
+   which yt-dlp
+   ```
+
+2. **If it returns nothing, set YT_DLP_PATH:**
+   ```bash
+   # Find where yt-dlp is located
+   find /usr -name yt-dlp 2>/dev/null
+   find ~ -name yt-dlp 2>/dev/null
+   
+   # Or if you downloaded it manually, use that path
+   ```
+
+3. **Add to .env.local:**
+   ```bash
+   YT_DLP_PATH=/full/path/to/yt-dlp
+   ```
+
+4. **Verify the path is correct:**
+   ```bash
+   ls -la "$YT_DLP_PATH"
+   # Should show the yt-dlp executable
+   ```
+
+### Path with spaces
+If your path contains spaces, use quotes in the environment variable:
+```bash
+YT_DLP_PATH="/Users/jeff/My Apps/yt-dlp_macos"
+```
+
+### Executable permissions
+Ensure yt-dlp has execute permissions:
+```bash
+chmod +x /path/to/yt-dlp
+```
+
+## Production Configuration
+
+For production deployments:
+
+1. Set environment variables in your hosting platform (Vercel, Railway, etc.)
+2. Ensure yt-dlp is installed on the server
+3. Set `YT_DLP_PATH` if yt-dlp is not in the default PATH
+
+### Vercel Example
+```bash
+# In Vercel dashboard → Settings → Environment Variables
+YT_DLP_PATH=/usr/local/bin/yt-dlp
+```
+
+### Docker Example
+```dockerfile
+# In Dockerfile
+ENV YT_DLP_PATH=/usr/local/bin/yt-dlp
+```
+
+## Next.js Environment Variables
+
+Next.js automatically loads `.env.local` files. Variables prefixed with `NEXT_PUBLIC_` are exposed to the browser, but `YT_DLP_PATH` should remain server-side only (no prefix).
+
+## Security Notes
+
+- Never commit `.env.local` to version control (already in .gitignore)
+- Keep yt-dlp paths secure
+- Use absolute paths for reliability
+- Test configuration after changes