Create Configuration wiki page with all env vars and runtime settings
parent
d920649da7
commit
6dd4a67806
1 changed files with 198 additions and 0 deletions
198
Configuration.md
Normal file
198
Configuration.md
Normal file
|
|
@ -0,0 +1,198 @@
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
| Meta | Value |
|
||||||
|
|------|-------|
|
||||||
|
| **Repo** | `xpltdco/tubearr` |
|
||||||
|
| **Page** | `Configuration` |
|
||||||
|
| **Audience** | developers, agents |
|
||||||
|
| **Last Updated** | 2026-04-04 |
|
||||||
|
| **Status** | current |
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
All configuration is managed through environment variables, parsed in `src/config/index.ts`. In development, use a `.env` file (loaded via dotenv). In Docker, set variables in `docker-compose.yml` or pass them with `-e`.
|
||||||
|
|
||||||
|
Some settings can also be changed at runtime via the API (`PUT /api/v1/system/settings`) and are persisted in the `systemConfig` database table.
|
||||||
|
|
||||||
|
## Environment Variables
|
||||||
|
|
||||||
|
### Server
|
||||||
|
|
||||||
|
| Variable | Type | Default | Description |
|
||||||
|
|----------|------|---------|-------------|
|
||||||
|
| `TUBEARR_PORT` | number | `8989` | HTTP server listen port |
|
||||||
|
| `NODE_ENV` | string | `development` | `development` or `production`. Affects logging format, Vite middleware, yt-dlp auto-update |
|
||||||
|
| `TUBEARR_LOG_LEVEL` | string | `info` | Fastify/Pino log level: `trace`, `debug`, `info`, `warn`, `error`, `fatal` |
|
||||||
|
|
||||||
|
### Storage
|
||||||
|
|
||||||
|
| Variable | Type | Default | Description |
|
||||||
|
|----------|------|---------|-------------|
|
||||||
|
| `TUBEARR_DB_PATH` | string | `./data/tubearr.db` | Path to SQLite database file. In Docker: `/config/tubearr.db` |
|
||||||
|
| `TUBEARR_MEDIA_PATH` | string | `./media` | Root directory for downloaded media files. In Docker: `/media` |
|
||||||
|
| `TUBEARR_COOKIE_PATH` | string | `./data/cookies` | Directory for per-platform cookie files. In Docker: `/config/cookies` |
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
| Variable | Type | Default | Description |
|
||||||
|
|----------|------|---------|-------------|
|
||||||
|
| `TUBEARR_API_KEY` | string | auto-generated UUID | API key for external access. If not set, a UUID is generated on first run and stored in the database |
|
||||||
|
|
||||||
|
### Scheduling
|
||||||
|
|
||||||
|
| Variable | Type | Default | Description |
|
||||||
|
|----------|------|---------|-------------|
|
||||||
|
| `TUBEARR_SCHEDULER_ENABLED` | boolean | `true` | Enable/disable the automatic channel monitoring scheduler |
|
||||||
|
| `TUBEARR_DEFAULT_CHECK_INTERVAL` | number | `360` | Default channel check interval in minutes (6 hours) |
|
||||||
|
|
||||||
|
### Rate Limiting
|
||||||
|
|
||||||
|
| Variable | Type | Default | Description |
|
||||||
|
|----------|------|---------|-------------|
|
||||||
|
| `TUBEARR_RATELIMIT_YOUTUBE_MS` | number | `1000` | Minimum milliseconds between YouTube API requests |
|
||||||
|
| `TUBEARR_RATELIMIT_SOUNDCLOUD_MS` | number | `3000` | Minimum milliseconds between SoundCloud API requests |
|
||||||
|
|
||||||
|
### Concurrency
|
||||||
|
|
||||||
|
| Variable | Type | Default | Description |
|
||||||
|
|----------|------|---------|-------------|
|
||||||
|
| `TUBEARR_CONCURRENT_DOWNLOADS` | number | `2` | Maximum number of simultaneous download tasks |
|
||||||
|
|
||||||
|
## Runtime Settings (via API)
|
||||||
|
|
||||||
|
These settings can be changed without restarting the application:
|
||||||
|
|
||||||
|
| Setting | API Path | Stored In |
|
||||||
|
|---------|----------|-----------|
|
||||||
|
| Check interval | `PUT /api/v1/system/settings` | `systemConfig.check_interval` |
|
||||||
|
| Concurrent downloads | `PUT /api/v1/system/settings` | `systemConfig.concurrent_downloads` |
|
||||||
|
| API key | `POST /api/v1/system/apikey/regenerate` | `systemConfig.api_key` |
|
||||||
|
|
||||||
|
## Platform Settings (via API)
|
||||||
|
|
||||||
|
Per-platform defaults configured through `PUT /api/v1/platform-settings/:platform`:
|
||||||
|
|
||||||
|
| Setting | Description | Applies To |
|
||||||
|
|---------|-------------|------------|
|
||||||
|
| `checkInterval` | Default monitoring interval (minutes) | New channels on this platform |
|
||||||
|
| `concurrencyLimit` | Max concurrent operations | Rate-limited per platform |
|
||||||
|
| `rateLimitDelay` | Milliseconds between requests | API throttling |
|
||||||
|
| `defaultMonitoringMode` | Default mode for new channels | `all`, `future`, `existing`, `none` |
|
||||||
|
| `grabAllEnabled` | Enable back-catalog import | Collect endpoints |
|
||||||
|
| `grabAllOrder` | Import order | `newest` or `oldest` first |
|
||||||
|
| `scanLimit` | Max items per scan | Monitoring checks |
|
||||||
|
| `subtitleLanguages` | Default subtitle languages | Comma-separated codes |
|
||||||
|
| `defaultFormatProfileId` | Default quality profile | New downloads |
|
||||||
|
|
||||||
|
## Format Profiles (via API)
|
||||||
|
|
||||||
|
Quality presets configured through `POST/PUT /api/v1/format-profile`:
|
||||||
|
|
||||||
|
| Option | Values | Description |
|
||||||
|
|--------|--------|-------------|
|
||||||
|
| `videoResolution` | `best`, `2160p`, `1440p`, `1080p`, `720p`, `480p`, `360p` | Target video resolution |
|
||||||
|
| `audioCodec` | `opus`, `aac`, `mp3`, `vorbis` | Preferred audio codec |
|
||||||
|
| `audioBitrate` | `320k`, `256k`, `192k`, `128k`, `96k`, `64k` | Audio quality |
|
||||||
|
| `containerFormat` | `mp4`, `mkv`, `webm`, `mp3`, `opus`, `m4a` | Output container |
|
||||||
|
| `embedSubtitles` | boolean | Embed subtitles in media file |
|
||||||
|
| `subtitleLanguages` | string | Comma-separated language codes (e.g., `en,es`) |
|
||||||
|
| `embedChapters` | boolean | Embed chapter markers |
|
||||||
|
| `embedThumbnail` | boolean | Embed thumbnail in metadata |
|
||||||
|
| `sponsorBlockRemove` | string | Comma-separated SponsorBlock categories to auto-remove |
|
||||||
|
|
||||||
|
**SponsorBlock categories:** `sponsor`, `selfpromo`, `interaction`, `intro`, `outro`, `preview`, `music_offtopic`, `filler`
|
||||||
|
|
||||||
|
## Notification Channels (via API)
|
||||||
|
|
||||||
|
Configured through `POST/PUT /api/v1/notification`:
|
||||||
|
|
||||||
|
### Discord
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "discord",
|
||||||
|
"config": {
|
||||||
|
"webhookUrl": "<your-discord-webhook-url>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Email
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "email",
|
||||||
|
"config": {
|
||||||
|
"smtpHost": "smtp.example.com",
|
||||||
|
"smtpPort": 587,
|
||||||
|
"username": "<your-email>",
|
||||||
|
"password": "<your-password>",
|
||||||
|
"to": "recipient@example.com"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pushover
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "pushover",
|
||||||
|
"config": {
|
||||||
|
"userKey": "<your-user-key>",
|
||||||
|
"apiToken": "<your-api-token>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Telegram
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "telegram",
|
||||||
|
"config": {
|
||||||
|
"botToken": "<your-bot-token>",
|
||||||
|
"chatId": "<your-chat-id>"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each notification channel has event toggles: `onGrab`, `onDownload`, `onFailure`.
|
||||||
|
|
||||||
|
## Docker Environment Defaults
|
||||||
|
|
||||||
|
When running in Docker (set automatically by the Dockerfile):
|
||||||
|
|
||||||
|
| Variable | Docker Default |
|
||||||
|
|----------|---------------|
|
||||||
|
| `NODE_ENV` | `production` |
|
||||||
|
| `TUBEARR_DB_PATH` | `/config/tubearr.db` |
|
||||||
|
| `TUBEARR_MEDIA_PATH` | `/media` |
|
||||||
|
| `TUBEARR_COOKIE_PATH` | `/config/cookies` |
|
||||||
|
|
||||||
|
## Example .env File
|
||||||
|
|
||||||
|
```env
|
||||||
|
# Server
|
||||||
|
TUBEARR_PORT=8989
|
||||||
|
NODE_ENV=development
|
||||||
|
TUBEARR_LOG_LEVEL=info
|
||||||
|
|
||||||
|
# Storage
|
||||||
|
TUBEARR_DB_PATH=./data/tubearr.db
|
||||||
|
TUBEARR_MEDIA_PATH=./media
|
||||||
|
TUBEARR_COOKIE_PATH=./data/cookies
|
||||||
|
|
||||||
|
# Auth (optional — auto-generated if not set)
|
||||||
|
# TUBEARR_API_KEY=your-uuid-here
|
||||||
|
|
||||||
|
# Scheduling
|
||||||
|
TUBEARR_SCHEDULER_ENABLED=true
|
||||||
|
TUBEARR_DEFAULT_CHECK_INTERVAL=360
|
||||||
|
|
||||||
|
# Rate limiting
|
||||||
|
TUBEARR_RATELIMIT_YOUTUBE_MS=1000
|
||||||
|
TUBEARR_RATELIMIT_SOUNDCLOUD_MS=3000
|
||||||
|
|
||||||
|
# Concurrency
|
||||||
|
TUBEARR_CONCURRENT_DOWNLOADS=2
|
||||||
|
```
|
||||||
Loading…
Add table
Reference in a new issue