Deploying Spooty

Introduction

Spooty is a self-hosted web application for managing and organizing your Spotify playlists. It provides tools for backing up playlists, finding duplicates, analyzing your music library, and performing bulk operations that Spotify’s native interface doesn’t support.

Built as a lightweight web application that connects to Spotify’s API, Spooty gives you additional control over your music collection while keeping your data under your control.

Key highlights of Spooty:

• Playlist Backup: Export playlists to JSON for backup and portability
• Duplicate Detection: Find and remove duplicate tracks across playlists
• Playlist Analysis: View statistics about your music collection
• Bulk Operations: Manage multiple playlists at once
• Track Sorting: Sort playlists by various criteria
• Export Options: Export playlists to various formats
• Privacy-Focused: Self-hosted, no third-party data storage
• OAuth Integration: Secure Spotify authentication
• Responsive Design: Works on desktop and mobile devices
• Open Source: Modify and extend as needed

This guide walks through deploying Spooty on Klutch.sh using Docker for personal Spotify playlist management.

Why Deploy Spooty on Klutch.sh

Deploying Spooty on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the container build and deployment automatically.

HTTPS by Default: Required for Spotify OAuth callbacks with automatic SSL.

Persistent Storage: Your backups and preferences persist across deployments.

GitHub Integration: Version control your configuration and deploy updates automatically.

Custom Domains: Use a memorable URL for your Spooty instance.

Always Available: Access your playlist tools from anywhere.

Privacy: Your Spotify data stays on your own instance.

Prerequisites

Before deploying Spooty on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A Spotify Developer account for API credentials
• Basic familiarity with Docker
• (Optional) A custom domain for your Spooty instance

Spotify Developer Setup

Before deploying, create a Spotify application:

1. Go to the Spotify Developer Dashboard
2. Click Create App
3. Fill in the app name and description
4. Add your callback URL: https://your-app-name.klutch.sh/callback
5. Note your Client ID and Client Secret

Deploying Spooty on Klutch.sh

Create a GitHub Repository

Create a new GitHub repository for your Spooty deployment.

Create Your Dockerfile

Create a Dockerfile in your repository:

FROM node:18-alpine AS builder

WORKDIR /app

# Clone and build Spooty
RUN apk add --no-cache git && \
    git clone https://github.com/your-spooty-repo/spooty.git . && \
    npm ci && \
    npm run build

FROM node:18-alpine

WORKDIR /app

COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/public ./public

# Create data directory
RUN mkdir -p /data

ENV NODE_ENV=production
ENV DATA_DIR=/data

EXPOSE 3000

HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

CMD ["npm", "start"]

Push Your Repository to GitHub

Commit and push your Dockerfile.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Configure the following environment variables:

Variable	Value
SPOTIFY_CLIENT_ID	Your Spotify application Client ID
SPOTIFY_CLIENT_SECRET	Your Spotify application Client Secret
SPOTIFY_REDIRECT_URI	https://your-app-name.klutch.sh/callback
SESSION_SECRET	A random string for session security

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/data	5 GB	Backups and application data

Deploy Your Application

Click Deploy to build and start Spooty.

Update Spotify Redirect URI

In the Spotify Developer Dashboard, update the redirect URI to match your actual deployment URL.

Access Spooty

Once deployment completes, access Spooty at https://your-app-name.klutch.sh and log in with Spotify.

Using Spooty

Connecting to Spotify

1. Navigate to your Spooty URL
2. Click Login with Spotify
3. Authorize the application
4. You’ll be redirected back with access to your library

Viewing Playlists

After authentication:

1. Your playlists appear on the dashboard
2. Click any playlist to view details
3. See track count, duration, and other statistics

Backing Up Playlists

To backup your playlists:

1. Select playlists to backup
2. Click Export or Backup
3. Choose export format (JSON, CSV, etc.)
4. Download or save to persistent storage

Finding Duplicates

To find duplicate tracks:

1. Select playlists to analyze
2. Click Find Duplicates
3. Review detected duplicates
4. Remove unwanted duplicates

Bulk Operations

Available bulk operations:

Operation	Description
Merge	Combine multiple playlists
Copy	Copy tracks between playlists
Sort	Sort playlist by criteria
Shuffle	Randomize playlist order
Filter	Remove tracks matching criteria

Playlist Analysis

Statistics Available

• Total tracks and duration
• Most common artists
• Genre distribution
• Decade distribution
• Playlist growth over time

Export Reports

Generate reports about your library:

1. Select analysis type
2. Choose date range
3. Export as PDF or spreadsheet

Data Management

Backup Strategy

Recommended backup approach:

1. Schedule regular playlist exports
2. Store backups in the persistent volume
3. Download backups periodically for off-site storage

Restoring Playlists

If you need to restore a playlist:

1. Import the backup file
2. Create a new Spotify playlist
3. Add tracks from the backup

Troubleshooting

OAuth Errors

• Verify redirect URI matches exactly
• Check Client ID and Secret are correct
• Ensure HTTPS is working

Cannot Load Playlists

• Re-authenticate with Spotify
• Check API rate limits
• Verify Spotify account permissions

Backups Not Saving

• Check persistent volume is mounted
• Verify write permissions
• Check available storage space

Additional Resources

• Spotify Web API Documentation
• Spotify Developer Dashboard
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Spooty on Klutch.sh gives you a personal Spotify playlist management tool with backup capabilities, duplicate detection, and bulk operations. With self-hosting, your Spotify data remains under your control while you gain features not available in the standard Spotify interface. Whether you’re organizing a massive collection or just want peace of mind with playlist backups, Spooty on Klutch.sh provides the tools you need.