documentation

docs/getting-started.md

@@ -0,0 +1,149 @@
+# 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.squid-inc.dev/connor/shanty:latest
+    ports:
+      - "8085:8085"
+      - "6080:6080"
+    volumes:
+      - ./config:/config
+      - shanty-data:/data
+      - /path/to/your/music:/music
+    environment:
+      - SHANTY_WEB_BIND=0.0.0.0
+    restart: unless-stopped
+
+volumes:
+  shanty-data:
+```
+
+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. |
+| `shanty-data` | Stores the database and downloaded files before they are organized. Managed by Docker. |
+| `/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.
+
+## 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.