Docker Setup
Yattee Server is a self-hosted video API server powered by yt-dlp. It extracts video streams, proxies playback, and optionally integrates with an Invidious instance to provide search, trending, channel browsing, captions, and thumbnails.
The official Docker image is published to Docker Hub as yattee/yattee-server and supports both linux/amd64 and linux/arm64 architectures.
System Requirements
- Docker (20.10 or later recommended)
- Docker Compose v2
Quick Start
Create a docker-compose.yml file:
services:
yattee-server:
image: yattee/yattee-server:latest
container_name: yattee-server
ports:
- "8085:8085"
volumes:
- downloads:/downloads
- data:/app/data
restart: unless-stopped
volumes:
downloads: # Temporary proxied video files
data: # Database and encryption keys
Start the server:
docker compose up -d
The server will be available at http://localhost:8085. On first launch you will be redirected to the Setup Wizard to create your admin account.
Volumes
Yattee Server uses two persistent volumes:
| Volume | Container Path | Purpose |
|---|---|---|
downloads | /downloads | Temporary storage for proxied video files during streaming |
data | /app/data | SQLite database (yattee.db) and encryption key (.encryption_key) |
The data volume is critical. It contains your SQLite database and the encryption key used to protect stored credentials. If you lose this volume, you will need to re-run the setup wizard and re-enter all credentials. Back up this volume regularly.
Environment Variables
All configuration is done through environment variables. The following table lists every available option:
| Variable | Default | Description |
|---|---|---|
HOST | 0.0.0.0 | Server bind address |
PORT | 8085 | Server port |
DATA_DIR | /app/data (Docker) | Directory for database, encryption keys, and temp files |
DOWNLOAD_DIR | /downloads (Docker) | Directory for proxied video downloads |
CREDENTIALS_ENCRYPTION_KEY | auto-generated | Fernet key for credential encryption. Auto-generated on first run and saved to DATA_DIR/.encryption_key |
CORS_ORIGINS | (empty) | Comma-separated list of allowed CORS origins |
CORS_ALLOW_ALL | false | Allow all origins (development only) |
CORS_ALLOW_CREDENTIALS | true | Allow credentials when specific origins are set |
DEBUG | false | Enable auto-reload for development |
SECURE_COOKIES | true | Require HTTPS for session cookies. Set to false only for local development without TLS |
YTDLP_SKIP_TLS_VERIFY | false | Skip TLS certificate verification in yt-dlp requests |
YT_EGRESS_PROXY | (empty) | HTTP or SOCKS5 proxy for all YouTube-bound traffic (yt-dlp, the direct InnerTube client, and the Invidious fallback path). Format: http://[user:pass@]host:port or socks5://host:port. See Egress Proxy below. |
SSRF_EXTRA_ALLOWED_CIDRS | (empty) | Comma-separated CIDRs to permit through the SSRF guard, in addition to the built-in allow list. Use when a backing service (e.g. an Invidious companion) lives on your LAN and returns stream URLs that point at private IPs. Example: 10.20.30.0/24 or 10.20.30.0/24,fd00::/8. Loopback is always blocked. See SSRF Protection. |
Instead of listing environment variables inline in docker-compose.yml, create a .env file in the same directory and reference it:
services:
yattee-server:
image: yattee/yattee-server:latest
env_file: .env
# ...
This keeps sensitive values out of your Compose file and makes it easier to manage configuration across environments.
Auto-Provisioning
You can skip the interactive setup wizard entirely by providing admin credentials and an optional Invidious URL as environment variables:
services:
yattee-server:
image: yattee/yattee-server:latest
container_name: yattee-server
ports:
- "8085:8085"
volumes:
- downloads:/downloads
- data:/app/data
environment:
- ADMIN_USERNAME=admin
- ADMIN_PASSWORD=your-secure-password
- INVIDIOUS_INSTANCE_URL=https://invidious.example.com
restart: unless-stopped
volumes:
downloads:
data:
When these variables are set, the server will automatically create the admin account and configure the Invidious proxy on first start. The INVIDIOUS_INSTANCE_URL variable is optional -- if omitted, the server will operate in yt-dlp-only mode.
Auto-provisioning only runs when no admin account exists yet. If the setup wizard has already been completed, these environment variables are ignored.
Egress Proxy
Some YouTube requests (rate limiting, regional restrictions, bot challenges) succeed more reliably when routed through a different IP than your server's default outbound address. YT_EGRESS_PROXY configures a single upstream proxy for all YouTube-bound traffic:
- yt-dlp — passed via
--proxy, used for video extraction and downloads - InnerTube client — the direct YouTube API path used for video metadata, search, and channel queries
- Invidious fallback — outbound calls when the server proxies its own request through the configured proxy
The proxy is not used for requests to your configured Invidious instance itself, for the admin UI, or for client-facing API responses.
services:
yattee-server:
image: yattee/yattee-server:latest
environment:
# ...
Both HTTP and SOCKS5 are supported:
# HTTP proxy with basic auth
# Plain HTTP proxy
YT_EGRESS_PROXY=http://10.0.0.5:8888
# SOCKS5
YT_EGRESS_PROXY=socks5://10.0.0.5:1080
The admin settings panel exposes a separate Enable egress proxy toggle. Turning it off ignores the configured proxy without clearing the value, which is useful for A/B testing whether the proxy is helping or hurting on a given day.
Building from Source
To build the Docker image locally from the source repository:
git clone https://github.com/yattee/yattee-server.git
cd yattee-server
docker compose up --build -d
This is useful for development or if you want to run the latest unreleased changes.
Updating
To update to the latest published image:
docker compose pull
docker compose up -d
The server will apply any necessary database migrations automatically on startup.
Next Steps
- Setup Wizard -- Create your admin account and configure initial settings
- Reverse Proxy -- Put Yattee Server behind nginx or Caddy for HTTPS access