Step-by-step instructions for Windows, Mac, and Linux. From installing Docker to streaming your first album — and going remote if you want.
⚡
One-Click Install
The fastest way to get SugarSpin running. The installer checks for Docker, finds your music folder, and launches everything automatically — on any machine, any CPU.
Open Terminal and run this single command. Works on Intel and Apple Silicon (M1/M2/M3).
# Download and run via Docker Compose
curl -O https://sugarspin.hotdang.studio/docker-compose-customer.yml
mv docker-compose-customer.yml docker-compose.yml
# Edit docker-compose.yml to set your music path, then:
docker compose up -d
After running the command: Open http://localhost:3333 in your browser, create your account, then go to Settings → Music Library and click Rescan Library. That's it!
New to Docker? Follow the step-by-step guide below. ↓
1
Install Docker on Your Machine
SugarSpin runs inside a Docker container, so Docker needs to be on the machine that will host your music. Pick your platform below.
Docker Desktop for Windows RECOMMENDED
The easiest way to get Docker on Windows. Includes a GUI so you can see and manage your containers without using the terminal.
Run the installer. When prompted, leave WSL 2 checked — this is the recommended backend.
3
Restart your computer when asked.
4
Launch Docker Desktop from the Start menu. It will finish setup on first run. Wait for the whale icon to appear in your taskbar — that means Docker is running.
Tip: You don't need to understand Docker to use it. Once Docker Desktop is running, you just need a terminal (PowerShell or Command Prompt) to run the SugarSpin command in the next step.
Docker Desktop for Mac RECOMMENDED
Works on both Apple Silicon (M1/M2/M3) and Intel Macs.
1
Go to docker.com/products/docker-desktop and choose the correct version — Apple Silicon or Intel Chip. Check → About This Mac to find out which you have.
2
Open the downloaded .dmg file and drag Docker to your Applications folder.
3
Launch Docker from Applications. It will ask for your password to install helper components — this is normal.
4
Wait for the whale icon to appear in your menu bar. When it shows "Docker Desktop is running", you're ready.
Alternative:OrbStack is a lighter, faster alternative to Docker Desktop on Mac that many users prefer. It's free for personal use and works identically for running SugarSpin.
Docker Engine for Linux RECOMMENDED
Install Docker Engine directly — no GUI needed. Works on Ubuntu, Debian, Fedora, and most major distros.
Ubuntu / Debian:
# Install Docker
curl -fsSL https://get.docker.com | sh
# Add your user to the docker group (so you don't need sudo)
sudo usermod -aG docker $USER
# Log out and back in, then verify Docker is working
docker --version
Install Container Manager from the Synology Package Center. Once installed, Docker is available via the GUI — no terminal required.
QNAP NAS
Install Container Station from the QNAP App Center. It provides a full Docker GUI similar to Synology's Container Manager.
UGREEN NAS
Docker comes pre-installed or is available as an app from the UGREEN UGOS app store. You can also SSH in and use Docker CLI directly.
Note: For NAS devices, jump straight to Step 2 — Docker is already available, just use the SSH terminal or your NAS's container GUI.
2
Pull & Run SugarSpin
SugarSpin lives on Docker Hub at rotrier66/sugarspin. Open a terminal (PowerShell on Windows, Terminal on Mac/Linux) and run the command for your platform.
# Replace C:/Users/YourName/Music with your actual music folder path
docker run -d \
--name sugarspin-player \
--restart unless-stopped \
-p 3333:3333 \
-v "C:/Users/YourName/Music:/music:ro" \
-v sugarspin-data:/app/data \
rotrier66/sugarspin:latest
Windows path tip: Use forward slashes in the path (e.g. C:/Users/Roger/Music) or a double backslash (C:\\Users\\Roger\\Music). On Mac/Linux use the normal path like /Users/roger/Music or /home/roger/Music.
GUI option: Open Container Manager, click Registry, search for rotrier66/sugarspin, download it, then create a container with port 3333 and your music folder mounted to /music.
Prefer Docker Compose? Download the compose file, edit your music path, and spin it up:
# Download the compose file
curl -O https://sugarspin.hotdang.studio/docker-compose-customer.yml
mv docker-compose-customer.yml docker-compose.yml
# Open docker-compose.yml in a text editor and update the music path# Then start it:
docker compose up -d
Confirm it's running: Run docker ps in your terminal. You should see sugarspin listed with status Up.
3
First Launch & Setting Up Your Library
Once the container is running, open your browser and visit:
http://localhost:3333
If you're opening from a different device on the same network (like a phone or tablet), use your server's local IP address instead:
http://192.168.x.x:3333
Finding your IP: On Windows run ipconfig in PowerShell, on Mac/Linux run ifconfig or ip addr in Terminal. Look for your local network IP — it usually starts with 192.168 or 10.0.
Create Your Account
On first launch you'll be prompted to create an admin account. Choose a username and password — this protects access to your music server.
Connect Your Music Library
1
After logging in, click the person icon in the left sidebar to go to your Account / Settings page.
2
Scroll down to the Settings tab (the gear icon). You'll see a Server Access section at the top — your full URL is listed there as a clickable link. Bookmark it!
3
Below that, find the Music Library section. The path to your music folder is shown here. Click Scan Library to index your collection — SugarSpin will read all your files and build your library.
4
Scanning can take a minute or two depending on how large your library is. When it's done, your albums, artists, and songs will all appear in the app.
Supported formats: FLAC, MP3, AAC, OGG, WAV, M4A — all lossless and lossy formats work out of the box.
4
Navigating SugarSpin
SugarSpin has a clean sidebar navigation. Here's a quick tour of every section:
🏠
Home
Your dashboard — recently added albums, quick access to recent plays, and a vibe check on what's in your library.
💿
Albums
Full album grid view. Click any album to see the track listing. Click a track to start playing from that point.
🎤
Artists
Browse by artist. Click an artist to see all their albums in your library.
🎵
Now Playing
The vinyl player view. Shows album art full-screen, animated record, and full playback controls. Click the note icon at the bottom-right to open it.
📋
Queue
Your current play queue. Drag to reorder, remove tracks, or clear it out. Queue up whole albums or individual songs.
❤️
Favorites
Tracks you've hearted. Build a personal collection of your most-played or most-loved songs.
The Player Bar
When music is playing, a player bar appears at the bottom of the screen with playback controls — play/pause, skip, shuffle, repeat, and volume. Click the note icon (♪) at the bottom-right of any page to jump to the full Now Playing vinyl view.
Search
The search bar at the top searches across your entire library — albums, artists, and song titles — instantly.
Settings (⚙️)
The gear icon in the sidebar opens your Settings page. From here you can:
→
Server Access — your full clickable URL (great for bookmarking from any device on the network)
→
Music Library — rescan your library if you've added new music
→
Watchtower — toggle the file watcher on/off (auto-detects new music added to your folder)
→
Playback settings — crossfade, audio quality, and more
Account (👤)
The person icon opens your account page where you can change your password, manage session settings (including require-login), view your license key, and check for SugarSpin updates.
5
Go Remote — Access From Anywhere
By default SugarSpin is only accessible on your local network. If you want to stream your music from your phone, car, or anywhere with internet, you have two great options:
Option A: Cloudflare Tunnel EASIEST
Cloudflare Tunnel creates a secure, public HTTPS URL for your SugarSpin without opening any ports on your router. Free and very fast.
Go to Zero Trust → Networks → Tunnels and click Create a tunnel.
3
Name your tunnel (e.g. sugarspin) and follow the install instructions to run cloudflared on your server machine. They provide a one-line install command.
4
Under Public Hostname, add a route: set the subdomain (e.g. music), your domain, and the service as http://localhost:3333.
5
Save. Your SugarSpin is now live at https://music.yourdomain.com from anywhere in the world.
Don't have a domain? Cloudflare offers free .trycloudflare.com tunnels for testing. For a permanent URL, you need a domain — they start at ~$10/year. Cloudflare also sells domains at cost.
Option B: Tailscale MOST PRIVATE
Tailscale creates an encrypted private network between your devices. Your music never touches a public server — it stays completely private. Free for personal use.
Install Tailscale on your server (the machine running SugarSpin): tailscale.com/download. Run tailscale up to connect it.
3
Install Tailscale on each client device (phone, laptop, etc.) you want to access SugarSpin from, and sign in with the same account.
4
In the Tailscale admin dashboard, find your server's Tailscale IP address (it looks like 100.x.x.x).
5
On any device connected to Tailscale, access SugarSpin at http://100.x.x.x:3333. Done — completely private, encrypted access from anywhere.
Enable MagicDNS in Tailscale settings to access your server by a friendly name like http://my-nas:3333 instead of an IP address.
Which one should I use? Cloudflare Tunnel is easier to set up and works from any browser with no app. Tailscale is more private and free forever but requires the Tailscale app on every device. Both work great with SugarSpin.
↑
Updating SugarSpin
When a new version of SugarSpin is released, you'll see an Update Available banner on your Account page inside the app. Here's what that means and how to apply it.
What the update does
SugarSpin runs as a Docker container. Updating means pulling the new container image from Docker Hub and restarting SugarSpin with it. Your music library, playlists, favorites, settings, and play history are all stored in a separate data volume — they are completely unaffected by the update.
How to update
Click Copy Update Command on your Account page. This copies the update command to your clipboard. How you run it depends on how you manage Docker on your machine:
NAS (QNAP, UGREEN, TrueNAS, Unraid, etc.) — Open your NAS's Docker management interface (Container Station, Container Manager, etc.), find the SugarSpin container, and use the "Update" or "Recreate" option. Most NAS Docker GUIs have a built-in way to pull a new image and restart — you don't need the command at all. Check your NAS's own documentation for the exact steps.
Mac with Docker Desktop — Open Terminal (search for it in Spotlight with ⌘Space), paste the copied command, and press Enter. Docker Desktop will handle the rest.
Windows with Docker Desktop — Open PowerShell or Command Prompt, paste the command, and press Enter.
Linux — Open a terminal, paste the command, and press Enter.
Once the update finishes, SugarSpin restarts automatically and you'll be on the latest version. Refresh your browser if the page doesn't update on its own.
I'm not comfortable running commands — what do I do?
If you're on a NAS, you almost certainly don't need to. Your NAS Docker interface can handle the update graphically — look for an "Update image" or "Recreate container" button next to the SugarSpin container. If you're unsure where to find it, search for "[your NAS brand] update Docker container" for specific instructions.
If you do need to use a terminal and aren't sure how, feel free to reach out at support@hotdang.studio — we're happy to walk you through it.
⇄
Transferring or Deactivating Your License
Your SugarSpin license is yours — it's not permanently locked to one machine. You can deactivate it and move it to a different machine whenever you need to.
When would I need to do this?
You're moving SugarSpin to a new NAS or a new computer
You reinstalled Docker and it's treating the machine as new
Your license shows as "free tier" after moving from one machine to another
You want to run SugarSpin on a different machine for a while
How to deactivate your license
Open SugarSpin in your browser and go to the Account page (click your avatar or username in the sidebar).
Scroll down to the License section. You'll see your current tier and license key.
Click Deactivate License. A confirmation prompt will appear — read it and confirm.
Your machine reverts to the free tier. Your library, playlists, and favorites are untouched.
Your license key is now free to be activated on another machine.
How to activate on the new machine
Install and launch SugarSpin on the new machine.
Go to the Account page and find the License section.
Enter your license key (the same one you used before — format: SS-GOLD-XXXX-XXXX-XXXX-XXXXXXXX).
Click Activate. Your full tier unlocks immediately — no rescan needed.
What if I can't access the old machine anymore?
If the old machine is gone, broken, or you no longer have access to it, contact us at support@hotdang.studio with your license key. We'll manually release the activation and you can re-activate on the new machine. This is always available — you're not stuck.
Do I need to buy a new license?
No. Never. One purchase is valid for as long as you use SugarSpin. You can deactivate and re-activate as many times as you need, on as many machines as your tier allows (Pro: 1 machine, Gold: 2 machines). Your license key does not expire.
Ready to unlock your full library?
The free tier covers 20 albums. Upgrade to Pro or Gold for unlimited music — one-time purchase, no subscriptions.
