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