Skip to content

Configuration

Jump to bottom
Jesse Slaton edited this page Mar 10, 2026 · 2 revisions

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

Library Path Considerations

When adding libraries in Stillwater and configuring connections to Emby, Jellyfin, or Lidarr, be aware that these servers may write metadata and images directly into your music directories. If multiple servers share the same library path, their background processes can overwrite each other's files, causing images to revert, NFO files to conflict, and metadata changes to not persist.

See Troubleshooting: Shared Library Paths for a full explanation and recommended configurations.

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.

Clone this wiki locally