Installation

Installation

Stillwater runs as a Docker container. It requires two volume mounts: one for persistent data (database, encryption key, backups) and one for your music library.

Docker Compose (Recommended)

Create a docker-compose.yml:

services:
  stillwater:
    image: ghcr.io/sydlexius/stillwater:latest
    container_name: stillwater
    ports:
      - "1973:1973"
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - /path/to/data:/data
      - /path/to/music:/music
    restart: unless-stopped

Then start it:

docker compose up -d

Docker CLI

docker run -d \
  --name stillwater \
  -p 1973:1973 \
  -e PUID=1000 \
  -e PGID=1000 \
  -v /path/to/data:/data \
  -v /path/to/music:/music \
  --restart unless-stopped \
  ghcr.io/sydlexius/stillwater:latest

Volumes

Container Path	Purpose
/data	Database (stillwater.db), encryption key, automated backups
/music	Your music library root (artist directories)

You can mount additional library paths if you have multiple music directories (e.g., /classical). Add each as a separate volume mount and register them as libraries in the app.

User/Group IDs

Set PUID and PGID to match the owner of your music files. This ensures Stillwater can read and write NFO files and images without permission errors.

# Find your user's UID and GID:
id $USER

First-Time Setup

1. Open http://your-server:1973 in a browser
2. Create an admin account (username and password)
3. The onboarding wizard walks you through:
   • Adding music library paths
   • Choosing your media server platform (Emby, Jellyfin, or Kodi)
   • Configuring metadata provider API keys
   • Optionally connecting to your media server or Lidarr

Updating

docker compose pull
docker compose up -d

The database is automatically migrated on startup when upgrading to a new version. Automated backups are enabled by default (see Configuration for backup settings).