Configuration

Configuration

Stillwater is configured via environment variables and/or a YAML config file. Environment variables take precedence over the config file.

Environment Variables

Variable	Default	Description
SW_PORT	1973	HTTP listen port
SW_BASE_PATH	/	URL base path for reverse proxy subfolder setups (e.g., /stillwater)
SW_DB_PATH	/data/stillwater.db	Path to the SQLite database file
SW_SESSION_SECRET	(auto-generated)	Secret for signing session cookies
SW_ENCRYPTION_KEY	(auto-generated)	AES-256 key for encrypting API keys at rest. Auto-generated on first run and saved to /data/encryption.key
SW_MUSIC_PATH	/music	Default music library root path
SW_SCANNER_EXCLUSIONS	Various Artists,Various,VA,Soundtrack,OST	Comma-separated list of directory names to exclude from scanning
SW_BACKUP_PATH	/data/backups	Directory for automated database backups
SW_BACKUP_RETENTION	7	Number of backup files to keep
SW_BACKUP_INTERVAL	24	Hours between automated backups
SW_BACKUP_ENABLED	true	Enable or disable automated backups (true/false)
SW_LOG_LEVEL	info	Log level: debug, info, warn, error
SW_LOG_FORMAT	json	Log format: json or text
PUID	99	User ID for the container process
PGID	100	Group ID for the container process

YAML Config File

Place a config.yaml in the /data volume:

server:
  port: 1973
  base_path: /

database:
  path: /data/stillwater.db

music:
  library_path: /music

scanner:
  depth: 1
  exclusions:
    - Various Artists
    - Various
    - VA
    - Soundtrack
    - OST

backup:
  path: /data/backups
  retention_count: 7
  interval_hours: 24
  enabled: true

logging:
  level: info
  format: json

Scanner Exclusions

The scanner skips top-level directories whose names match the exclusion list (case-insensitive). These compilation/soundtrack folders lack single-artist metadata.

To customize exclusions via environment variable:

environment:
  - SW_SCANNER_EXCLUSIONS=Various Artists,Various,VA,Soundtrack,OST,Compilations

Or in config.yaml:

scanner:
  exclusions:
    - Various Artists
    - Various
    - VA
    - Soundtrack
    - OST
    - Compilations

Base Path (Subfolder Reverse Proxy)

If you serve Stillwater under a subfolder (e.g., https://example.com/stillwater/), set SW_BASE_PATH:

environment:
  - SW_BASE_PATH=/stillwater

See Reverse Proxy for full Nginx/SWAG configuration examples.