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](https://docs.docker.com/engine/install/) for your distribution.
- **Mac/Windows:** Install [Docker Desktop](https://www.docker.com/products/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:

```sh
mkdir shanty && cd shanty
```

Create `docker-compose.yml` with these contents:

```yaml
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`:

```sh
docker compose up -d
```

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

```sh
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](features/musicbrainz-db.md) -- 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](features/youtube-auth.md) 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](features/subsonic.md) 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](features/youtube-auth.md) 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:
```sh
docker compose exec shanty ./shanty mb-import --download
```

See the [MusicBrainz Database guide](features/musicbrainz-db.md) for more details.

## What next?

- Set up [monitoring](features/monitoring.md) to automatically detect new releases from your favorite artists.
- Generate [playlists](features/playlists.md) from your library using similar-artist data.
- Check the [Configuration Reference](configuration.md) to customize download formats, organization templates, and scheduling.