Main/docs/getting-started.md

Getting Started

This guide walks you through setting up Shanty from scratch. By the end, you will have a running instance that can search for music, download it, and play it on your phone.

Prerequisites

You need Docker and Docker Compose installed on your computer or server. If you do not have them:

• Linux: Follow the Docker install guide for your distribution.
• Mac/Windows: Install Docker Desktop.

You also need a folder where you want your music library stored.

Step 1: Create a docker-compose.yml

Create a new folder for your Shanty configuration, then create a file called docker-compose.yml inside it:

mkdir shanty && cd shanty

Create docker-compose.yml with these contents:

services:
  shanty:
    image: git.rcjohnstone.com/connor/shanty:latest
    ports:
      - "8085:8085"
      # - "6080:6080"  # Optional: expose if YouTube login iframe doesn't load
    volumes:
      - ./config:/config
      - ./data:/data
      - /path/to/your/music:/music
    environment:
      - SHANTY_WEB_BIND=0.0.0.0
    restart: unless-stopped

Replace /path/to/your/music with the actual path to where you want your music stored. For example, /home/yourname/Music on Linux or /Users/yourname/Music on Mac.

What the volumes do

Mount point	Purpose
./config	Stores your configuration file (config.yaml). Lives next to your docker-compose.yml.
./data	Stores the database, downloaded files, and MusicBrainz data. Put this on an SSD if possible.
/music	Your music library. This is where organized, tagged music ends up.

Step 2: Start the container

From the folder containing your docker-compose.yml:

docker compose up -d

Wait a few seconds for the container to start. You can check the logs with:

docker compose logs -f

You should see a line like starting server bind=0.0.0.0:8085. Press Ctrl+C to stop watching logs (the container keeps running).

Step 3: Create your account

Open your browser and go to:

http://localhost:8085

If Shanty is running on another machine, replace localhost with that machine's IP address.

On first launch, you will see a setup screen. Choose a username and password (at least 4 characters). This creates an admin account.

Step 4: Search and watch an artist

1. Click the Search tab in the navigation.
2. Type an artist name (for example, "Pink Floyd") and press Enter.
3. Click on the artist in the search results to view their discography.
4. Click Watch All to add their entire discography to your watchlist. Or click individual albums to watch specific ones.

You will see the artist appear on the Library page with track counts showing how many tracks are wanted versus owned.

Note: Browsing artist discographies may be slow on the first visit (30-60 seconds per artist) because Shanty queries MusicBrainz one request at a time. This gets much faster after the first visit (results are cached). For instant lookups, you can import the MusicBrainz database locally -- but this is optional and can be done later.

Step 5: Download your music

Click the Set Sail button on the Dashboard. This runs the full pipeline:

1. Sync -- creates download jobs for all wanted tracks
2. Download -- fetches audio from YouTube Music via yt-dlp
3. Tag -- writes MusicBrainz metadata to the files
4. Organize -- moves files into your music library in a clean folder structure

You can watch progress on the Dashboard. The download queue shows each track as it is processed.

Depending on how many tracks you are downloading, this can take a while. YouTube has rate limits (roughly 250 downloads per hour without authentication). See the YouTube Authentication guide to increase this to roughly 1800 per hour.

Step 6 (Optional): Set up Subsonic for mobile playback

Shanty includes a Subsonic-compatible API that lets you stream your library from mobile apps like Ultrasonic, DSub, or Symfonium.

1. In the Shanty web UI, go to Settings.
2. Find the Subsonic API section.
3. Set a Subsonic password. This is separate from your web login password.
4. On your phone, install a Subsonic client (Ultrasonic for Android is free and works well).
5. In the client, add a server with the URL http://your-server-ip:8085. The client adds /rest automatically.
6. Enter your Shanty username and the Subsonic password you just set.

See the Subsonic guide for more details and recommended clients.

Step 7 (Optional): Set up YouTube authentication

Without authentication, YouTube limits you to roughly 250 downloads per hour. With authentication, this increases to roughly 1800 per hour. You also get access to age-restricted content.

1. Go to Settings in the Shanty web UI.
2. Find the YouTube Authentication section and click Authenticate.
3. A browser window opens in your browser via noVNC. Log in to a Google account.
4. Click Done when finished.

Important: Use a throwaway Google account. There is a small risk of account restrictions. See the YouTube Authentication guide for details.

Step 8 (Optional): Import the MusicBrainz database

MusicBrainz has a rate limit of 1 request every 1.1 seconds. When you browse a new artist, loading their full discography can take 30-60 seconds. Importing the MusicBrainz database locally makes these lookups instant.

This requires about 24 GB of download space, produces a 16 GB database, and takes 12-24 hours for the initial import. An SSD is strongly recommended.

To start the import from the web UI:

1. Go to Settings.
2. Find the MusicBrainz Database section.
3. Click Import.

Or from the command line:

docker compose exec shanty ./shanty mb-import --download

See the MusicBrainz Database guide for more details.

What next?

• Set up monitoring to automatically detect new releases from your favorite artists.
• Generate playlists from your library using similar-artist data.
• Check the Configuration Reference to customize download formats, organization templates, and scheduling.