Skip to main content
Plank uses environment variables for all configuration. These are typically defined in a .env file in the project root.

​
Quick Reference

VariableRequiredDefaultDescription
DATABASE_URL✓./plank.dbPath to SQLite database file
DATA_PATH✓./dataDirectory for downloaded files
TMDB_API_KEY✓-TMDB API key for movie/TV metadata
PROWLARR_URL-http://localhost:9696Prowlarr API base URL
PUBLIC_PROWLARR_URL-${PROWLARR_URL}Public-facing Prowlarr URL
PROWLARR_API_KEY--Prowlarr API key (auto-configured in Docker)
PROWLARR_CONFIG_PATH--Path to Prowlarr config.xml (Docker only)
FLARESOLVERR_URL--FlareSolverr URL for captcha solving
OPENSUBTITLES_API_KEY--OpenSubtitles API key
OPENSUBTITLES_USERNAME--OpenSubtitles account username
OPENSUBTITLES_PASSWORD--OpenSubtitles account password
BETTER_AUTH_SECRET✓-Secret key for authentication (32+ chars)
BETTER_AUTH_URL✓http://localhost:3300Base URL for authentication callbacks
ENABLE_FILE_STORAGE-trueSave downloaded files to disk
PORT-3300Server port number
HOST-0.0.0.0Server host binding (Docker: 0.0.0.0)
ORIGINDockerhttp://localhost:3300Public URL for CSRF protection
TZ-America/New_YorkTimezone (Prowlarr/FlareSolverr)
MEDIA_PATH-./mediaHost path for media library (Docker)

​
Database Configuration

​
DATABASE_URL

​
DATABASE_URL
string
required
Path to the SQLite database file. Can be relative or absolute.
Examples: 
# Relative path (default)
DATABASE_URL=./plank.db

# Absolute path
DATABASE_URL=/var/lib/plank/plank.db

# Docker (inside container)
DATABASE_URL=/app/db/plank.db
The database file will be created automatically on first run. Ensure the directory is writable.

​
DATA_PATH

​
DATA_PATH
string
required
Directory where torrent files are downloaded and stored.
Examples: 
# Relative path (default)
DATA_PATH=./data

# Absolute path
DATA_PATH=/mnt/storage/plank

# Docker (inside container)
DATA_PATH=/app/data
Ensure sufficient disk space. A single 4K movie can be 40GB+.

​
TMDB_API_KEY

​
TMDB_API_KEY
string
required
API key from The Movie Database for fetching movie/TV show metadata, posters, and descriptions.
Get your API key:
  1. Create an account at themoviedb.org
  2. Go to Settings → API
  3. Request an API key (choose “Developer” option)
  4. Copy the API Key (v3 auth)
TMDB_API_KEY=your_api_key_here_32_characters_long
Search functionality requires a valid TMDB API key. Without it, you can only add content via magnet links.

​
Prowlarr Configuration

Prowlarr provides torrent search functionality by aggregating multiple indexers.

​
PROWLARR_URL

​
PROWLARR_URL
string
default:"http://localhost:9696"
Internal URL for Plank to communicate with Prowlarr.
Examples: 
# Bare metal (localhost)
PROWLARR_URL=http://localhost:9696

# Docker (service name)
PROWLARR_URL=http://prowlarr:9696

# Remote Prowlarr instance
PROWLARR_URL=http://192.168.1.100:9696
In Docker, always use the service name (prowlarr) instead of localhost.

​
PUBLIC_PROWLARR_URL

​
PUBLIC_PROWLARR_URL
string
Public-facing URL for accessing Prowlarr. Defaults to PROWLARR_URL.
Useful when Plank and Prowlarr are accessed via different URLs: 
PROWLARR_URL=http://prowlarr:9696
PUBLIC_PROWLARR_URL=http://192.168.1.100:9696

​
PROWLARR_API_KEY

​
PROWLARR_API_KEY
string
API key for authenticating with Prowlarr. Auto-configured in Docker deployments.
Docker: Leave blank - automatically extracted from Prowlarr’s config. Bare Metal: Get from Prowlarr:
  1. Access Prowlarr at http://localhost:9696
  2. Go to Settings → General
  3. Copy the API Key
# Docker (auto-configured)
PROWLARR_API_KEY=

# Bare metal (manual)
PROWLARR_API_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
PROWLARR_CONFIG_PATH

​
PROWLARR_CONFIG_PATH
string
Path to Prowlarr’s config.xml file (Docker only). Used to auto-extract the API key.
# Docker (automatic)
PROWLARR_CONFIG_PATH=/prowlarr-config/config.xml
This is only used in Docker deployments where Prowlarr’s config volume is mounted into the Plank container.

​
FlareSolverr Configuration

​
FLARESOLVERR_URL

​
FLARESOLVERR_URL
string
URL to FlareSolverr service for solving captchas on torrent sites.
Examples: 
# Docker (service name)
FLARESOLVERR_URL=http://flaresolverr:8191

# Bare metal (localhost)
FLARESOLVERR_URL=http://localhost:8191

# Remote instance
FLARESOLVERR_URL=http://192.168.1.100:8191
FlareSolverr is configured in Prowlarr, not directly in Plank. This variable is for Prowlarr to use.

​
Subtitle Configuration

OpenSubtitles provides subtitle downloads in multiple languages.

​
OPENSUBTITLES_API_KEY

​
OPENSUBTITLES_API_KEY
string
API key from OpenSubtitles.com for downloading subtitles.
Get your API key:
  1. Create an account at opensubtitles.com
  2. Go to Consumers
  3. Create a new application
  4. Copy the API key
OPENSUBTITLES_API_KEY=your_api_key_here

​
OPENSUBTITLES_USERNAME

​
OPENSUBTITLES_USERNAME
string
Your OpenSubtitles account username.
OPENSUBTITLES_USERNAME=your_username

​
OPENSUBTITLES_PASSWORD

​
OPENSUBTITLES_PASSWORD
string
Your OpenSubtitles account password.
OPENSUBTITLES_PASSWORD=your_password
Without OpenSubtitles configuration, subtitle functionality will be disabled.

​
Authentication

​
BETTER_AUTH_SECRET

​
BETTER_AUTH_SECRET
string
required
Secret key for encrypting session tokens and cookies. Must be at least 32 characters.
Generate a secure secret: 
# Using OpenSSL
openssl rand -hex 32

# Using Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

BETTER_AUTH_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
Never share this secret publicly. Changing it will invalidate all existing user sessions.

​
BETTER_AUTH_URL

​
BETTER_AUTH_URL
string
default:"http://localhost:3300"
required
Base URL for authentication callbacks and redirects. Must match the URL users access Plank from.
Examples: 
# Local development
BETTER_AUTH_URL=http://localhost:3300

# Local network
BETTER_AUTH_URL=http://192.168.1.100:3300

# Production with domain
BETTER_AUTH_URL=https://plank.yourdomain.com
Include the protocol (http:// or https://) and port if non-standard.

​
Server Configuration

​
PORT

​
PORT
number
default:"3300"
Port number the server listens on.
# Default
PORT=3300

# Custom port
PORT=8080
In Docker, this is the internal container port (usually 3000). The host port is configured in docker-compose.yml.

​
HOST

​
HOST
string
default:"0.0.0.0"
Network interface to bind to.
# Listen on all interfaces (Docker, production)
HOST=0.0.0.0

# Listen on localhost only (development)
HOST=127.0.0.1

​
ORIGIN

​
ORIGIN
string
required
Public URL users access Plank from. Required for Docker to prevent CSRF errors.
Examples: 
# Local access
ORIGIN=http://localhost:3300

# Network access
ORIGIN=http://192.168.1.100:3300

# Domain with HTTPS
ORIGIN=https://plank.yourdomain.com
Docker users: If you get “Cross-site POST form submissions are forbidden”, ensure ORIGIN matches your browser URL exactly.

​
Storage Configuration

​
ENABLE_FILE_STORAGE

​
ENABLE_FILE_STORAGE
boolean
default:"true"
Whether to save downloaded files to disk. Reserved for future functionality.
ENABLE_FILE_STORAGE=true
Keep this as true. Setting to false may cause issues in the current version.

​
MEDIA_PATH

​
MEDIA_PATH
string
default:"./media"
Host directory for media library (Docker only). Mounted at /app/data/library inside the container.
# Default (relative to docker-compose.yml)
MEDIA_PATH=./media

# Absolute path
MEDIA_PATH=/mnt/storage/media

# Network share
MEDIA_PATH=/mnt/nas/media

​
Timezone

​
TZ

​
TZ
string
default:"America/New_York"
Timezone for Prowlarr and FlareSolverr containers.
Examples: 
TZ=America/New_York
TZ=Europe/London
TZ=Asia/Tokyo
TZ=UTC
See list of tz database time zones.

​
Example Configurations

​
Minimal Docker Configuration

.env
# Required
TMDB_API_KEY=your_tmdb_api_key
BETTER_AUTH_SECRET=your-random-32-char-secret
BETTER_AUTH_URL=http://localhost:3300
ORIGIN=http://localhost:3300

# Optional (Prowlarr auto-configured)
PROWLARR_API_KEY=

​
Full Docker Configuration

.env
# Database
DATABASE_URL=/app/db/plank.db
DATA_PATH=/app/data

# Metadata
TMDB_API_KEY=your_tmdb_api_key

# Prowlarr (auto-configured)
PROWLARR_URL=http://prowlarr:9696
PUBLIC_PROWLARR_URL=http://192.168.1.100:9696
PROWLARR_API_KEY=
FLARESOLVERR_URL=http://flaresolverr:8191

# Subtitles
OPENSUBTITLES_API_KEY=your_opensubtitles_api_key
OPENSUBTITLES_USERNAME=your_username
OPENSUBTITLES_PASSWORD=your_password

# Authentication
BETTER_AUTH_SECRET=your-random-32-char-secret
BETTER_AUTH_URL=http://192.168.1.100:3300

# Server
PORT=3000
HOST=0.0.0.0
ORIGIN=http://192.168.1.100:3300
ENABLE_FILE_STORAGE=true

# Docker specific
TZ=America/New_York
MEDIA_PATH=/mnt/storage/media

​
Bare Metal Configuration

.env
# Database
DATABASE_URL=./plank.db
DATA_PATH=./data

# Metadata
TMDB_API_KEY=your_tmdb_api_key

# Prowlarr (manual configuration)
PROWLARR_URL=http://localhost:9696
PUBLIC_PROWLARR_URL=http://localhost:9696
PROWLARR_API_KEY=your_prowlarr_api_key_from_settings

# Subtitles
OPENSUBTITLES_API_KEY=your_opensubtitles_api_key
OPENSUBTITLES_USERNAME=your_username
OPENSUBTITLES_PASSWORD=your_password

# Authentication
BETTER_AUTH_SECRET=your-random-32-char-secret
BETTER_AUTH_URL=http://localhost:3300

# Server
PORT=3300
ENABLE_FILE_STORAGE=true

​
Production with HTTPS

.env
# Production settings
NODE_ENV=production

# Database
DATABASE_URL=/var/lib/plank/plank.db
DATA_PATH=/var/lib/plank/data

# Metadata
TMDB_API_KEY=your_tmdb_api_key

# Prowlarr
PROWLARR_URL=http://prowlarr:9696
PUBLIC_PROWLARR_URL=https://prowlarr.yourdomain.com
PROWLARR_API_KEY=your_prowlarr_api_key

# Subtitles
OPENSUBTITLES_API_KEY=your_opensubtitles_api_key
OPENSUBTITLES_USERNAME=your_username
OPENSUBTITLES_PASSWORD=your_password

# Authentication
BETTER_AUTH_SECRET=very-long-random-production-secret-string
BETTER_AUTH_URL=https://plank.yourdomain.com

# Server (behind reverse proxy)
PORT=3000
HOST=127.0.0.1
ORIGIN=https://plank.yourdomain.com
ENABLE_FILE_STORAGE=true

​
Security Best Practices

  1. Never commit .env files to version control 
    # Add to .gitignore
echo ".env" >> .gitignore
  2. Use strong secrets (32+ characters, random) 
    BETTER_AUTH_SECRET=$(openssl rand -hex 32)
  3. Restrict file permissions 
    chmod 600 .env
  4. Use environment-specific values
    • Development: http://localhost:3300
    • Production: https://plank.yourdomain.com
  5. Rotate secrets periodically (invalidates existing sessions)

​
Troubleshooting

Ensure .env is in the project root and properly formatted:
# Correct
TMDB_API_KEY=abc123

# Incorrect (spaces around =)
TMDB_API_KEY = abc123

# Incorrect (quotes not needed)
TMDB_API_KEY="abc123"
Test loading:
# Source the file
set -a; source .env; set +a
echo $TMDB_API_KEY
Ensure ORIGIN matches your browser URL exactly:
# Browser URL: http://192.168.1.100:3300
ORIGIN=http://192.168.1.100:3300

# Not: http://localhost:3300
Restart after changing:
docker compose -f docker/docker-compose.yml restart plank
Docker: Verify service name (not localhost):
PROWLARR_URL=http://prowlarr:9696
Bare Metal: Verify Prowlarr is running:
curl http://localhost:9696
Check API key matches Prowlarr settings:
  • Prowlarr → Settings → General → API Key
Verify BETTER_AUTH_SECRET is set and at least 32 characters:
# Generate new secret
openssl rand -hex 32
Ensure BETTER_AUTH_URL matches your access URL:
# If accessing via http://192.168.1.100:3300
BETTER_AUTH_URL=http://192.168.1.100:3300

​
Next Steps

Docker Setup

Configure Docker deployment

Bare Metal Setup

Install on your system

Prowlarr Configuration

Set up torrent indexers

Security Guide

VPN setup and best practices

Build docs developers (and LLMs) love

Get started for freeTalk to us