Skip to content
Klutch.sh Docs

Deploying Beets

Beets is a lightweight, open-source music library manager and metadata tagger that helps you organize, curate, and enjoy your music collection. Designed for music enthusiasts and professionals alike, Beets automates the tedious process of organizing music files, fetching metadata from multiple sources, and managing your entire music library with precision and ease. Whether you have hundreds or hundreds of thousands of songs, Beets provides powerful tools to keep your music organized and metadata accurate.

Why Beets?

Beets stands out in the music management landscape with its powerful features and flexibility:

  • Automatic Tagging: Intelligently matches songs to online metadata databases, automatically filling in artist, album, track information with minimal errors
  • Metadata Sources: Integrates with multiple metadata providers including MusicBrainz, Discogs, and Spotify for comprehensive and accurate information
  • Flexible Organization: Organize music files by artist, album, year, genre, or custom naming schemes
  • Audio Quality Detection: Identifies and manages bitrate, format, and audio quality of your files
  • Plugin Ecosystem: Extend functionality with official and community plugins for additional features
  • Web Interface: Optional web-based interface for browsing and managing your library remotely
  • Import Management: Smart duplicate detection and handling during library imports
  • Format Conversion: Optional audio transcoding and format conversion capabilities
  • Batch Operations: Efficiently manage and organize large music collections
  • Command-Line Interface: Powerful CLI for scripting and automation
  • Cross-Platform: Works on Linux, macOS, Windows, and Docker containers
  • Open Source: MIT licensed with active community development and support

Beets is perfect for music lovers, audio professionals, and anyone who wants complete control over their music library organization. With persistent storage on Klutch.sh, your music collection and metadata are always safe, searchable, and accessible.

Prerequisites

Before deploying Beets, ensure you have:

  • A Klutch.sh account
  • A GitHub repository with your Beets deployment configuration
  • Basic familiarity with Docker and Git
  • (Optional) A music library to organize (can be empty initially)

Deploying Beets

  1. Create a New Project

    Log in to your Klutch.sh dashboard and create a new project for your Beets deployment.

  2. Prepare Your Repository

    Create a GitHub repository with the following structure for your Beets deployment:

    beets-deploy/
    ├─ Dockerfile
    ├─ config.yaml
    ├─ .gitignore
    └─ README.md

    Here’s a production-ready Dockerfile for Beets:

    FROM python:3.11-slim
    

    WORKDIR /app
    

    # Install system dependencies
    RUN apt-get update && apt-get install -y \
        git \
        curl \
        ffmpeg \
        imagemagick \
        && rm -rf /var/lib/apt/lists/*
    

    # Install Beets and common plugins
    RUN pip install --no-cache-dir \
        beets \
        beautifulsoup4 \
        flask \
        requests
    

    # Create necessary directories
    RUN mkdir -p /music /app/config /app/logs
    

    # Expose port 8337 for web interface
    EXPOSE 8337
    

    # Set working directory for Beets
    WORKDIR /music
    

    # Copy configuration
    COPY config.yaml /app/config/config.yaml
    

    # Health check
    HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
      CMD curl -f http://localhost:8337 || exit 1
    

    # Start Beets with web interface
    CMD ["beet", "web", "-l", "0.0.0.0", "-p", "8337"]

    Create a config.yaml file for Beets configuration:

    directory: /music/library
    library: /app/config/library.db
    import:
      autotag: yes
      write: yes
      copy: yes
      timid: no
      log: /app/logs/import.log
    

    plugins:
      - web
      - thumbnails
      - mbsync
      - lyrics
    

    web:
      host: 0.0.0.0
      port: 8337
    

    musicbrainz:
      enabled: yes
    

    import:
      resume: ask

    Commit and push to your GitHub repository:

    Terminal window
    git init
    git add .
    git commit -m "Initial Beets deployment"
    git remote add origin https://github.com/yourusername/beets-deploy.git
    git push -u origin main

  3. Create a New App

    In the Klutch.sh dashboard:

    • Click “Create New App”
    • Select your GitHub repository containing the Dockerfile
    • Choose the branch (typically main or master)
    • Klutch.sh will automatically detect the Dockerfile in the root directory

  4. Configure Environment Variables

    Set up these environment variables in your Klutch.sh dashboard:

    VariableDescriptionExample
    PYTHONUNBUFFEREDPython output buffering1
    BEETSDIRBeets configuration directory/app/config
    MUSICBRAINZ_RATE_LIMITMusicBrainz API rate limit (requests per second)1
    ACOUSTIDAPI_KEYAcoustID API key (optional for audio fingerprinting)your-api-key
    DISCOGS_TOKENDiscogs API token (optional for Discogs metadata)your-token

  5. Configure Persistent Storage

    Beets requires persistent storage for your music library and metadata database. Add persistent volumes:

    Mount PathDescriptionRecommended Size
    /music/libraryYour music collection500GB+ (adjust based on library size)
    /app/configBeets configuration and database10GB

    In the Klutch.sh dashboard:

    • Navigate to your app settings
    • Go to the “Volumes” section
    • Click “Add Volume” for each mount path
    • Set mount paths and sizes as specified above

  6. Set Network Configuration

    Configure your app’s network settings:

    • Select traffic type: HTTP
    • Internal port: 8337 (the Beets web interface port)
    • Klutch.sh will automatically handle HTTPS termination

  7. Deploy Your App

    • Review all settings
    • Click “Deploy”
    • Klutch.sh will build the Docker image and start your Beets instance
    • Wait for the deployment to complete (typically 3-5 minutes)

Initial Setup and Configuration

After deployment completes, access your Beets instance:

Accessing the Web Interface

Navigate to your app’s URL: https://example-app.klutch.sh

You’ll see the Beets web interface showing your music library. Initially, it will be empty until you import music.

Importing Your Music Library

The primary way to add music to Beets is through the import process:

  1. Prepare Your Music

    • Place your music files in an easily accessible location
    • Supported formats: MP3, FLAC, OGG, M4A, WMA, and more

  2. Import from Web Interface (if enabled)

    • Use the web interface to browse and import music
    • Beets will automatically fetch metadata and organize files

  3. Import via Command Line (advanced)

    • SSH into your Beets instance and run:
      Terminal window
      beet import /path/to/music

Configuration Best Practices

In your config.yaml:

directory: /music/library          # Main music library directory
library: /app/config/library.db    # Database location
import:
  autotag: yes                      # Automatically tag imports
  write: yes                        # Write metadata to files
  copy: yes                         # Copy files to library directory
  timid: no                         # Require user confirmation for changes
  log: /app/logs/import.log        # Log import operations


plugins:
  - web                            # Web interface
  - thumbnails                     # Album artwork
  - mbsync                         # Keep metadata in sync
  - lyrics                         # Fetch lyrics


web:
  host: 0.0.0.0                    # Listen on all interfaces
  port: 8337                       # Web interface port


musicbrainz:
  enabled: yes                     # Use MusicBrainz for tagging

Environment Variables and Configuration

Basic Beets Configuration

Terminal window
PYTHONUNBUFFERED=1
BEETSDIR=/app/config
MUSICBRAINZ_RATE_LIMIT=1

Advanced Configuration

For fine-tuned control over Beets behavior:

Terminal window
BEETS_AUTO_UPDATE_CACHE=true
BEETS_IMPORT_RESUME=ask
BEETS_IMPORT_QUIET=false
BEETS_IMPORT_VERBOSE=false
BEETS_LIBRARY_SIZE_LIMIT=1000000
BEETS_LOG_LEVEL=info

Plugin Configuration

Enable and configure optional plugins:

Terminal window
# Enable album art downloading
ENABLE_THUMBNAILS=true


# Enable lyrics fetching
ENABLE_LYRICS=true


# Enable MusicBrainz sync
ENABLE_MBSYNC=true


# Discogs plugin
ENABLE_DISCOGS=true
DISCOGS_TOKEN=your-discogs-token

Sample Code and Getting Started

Using the Beets Web Interface

Once deployed and music is imported, you can:

  1. Browse Your Library

    • View albums, artists, and genres
    • Search for specific songs or albums
    • Filter by various criteria

  2. View Metadata

    • See all tag information for songs
    • View album artwork and metadata
    • Check import status and logs

Command-Line Examples (if SSH access available)

Terminal window
# List all albums in library
beet list -a


# List all songs by an artist
beet list artist:Radiohead


# Search for songs with missing metadata
beet list -f '$artist - $title' mb:none


# Update library statistics
beet stats


# Modify metadata for a song
beet modify artist:Radiohead title:Creep artist="Radiohead"

Importing Music Programmatically

Terminal window
# Import a directory with automatic tagging
beet import -s /music/incoming


# Import with manual confirmation for each album
beet import /music/incoming


# Import and overwrite existing files
beet import -W /music/incoming


# Import from remote location
beet import /mnt/external-drive/music

API Examples (Web Interface)

Terminal window
# Get library statistics (if API available)
curl https://example-app.klutch.sh/api/stats


# Search the library (if API available)
curl "https://example-app.klutch.sh/api/search?q=radiohead"


# Get album information (if API available)
curl "https://example-app.klutch.sh/api/albums/1"

Docker Compose for Local Development

For local testing before deploying to Klutch.sh:

version: '3.8'


services:
  beets:
    image: python:3.11-slim
    working_dir: /music
    volumes:
      - ./music:/music/library
      - ./config:/app/config
      - ./logs:/app/logs
    ports:
      - "8337:8337"
    environment:
      - PYTHONUNBUFFERED=1
      - BEETSDIR=/app/config
      - MUSICBRAINZ_RATE_LIMIT=1
    command: >
      bash -c "pip install beets beautifulsoup4 flask requests &&
               beet web -l 0.0.0.0 -p 8337"
    restart: unless-stopped

Save as docker-compose.yml and run:

Terminal window
docker-compose up -d

Access Beets web interface at http://localhost:8337

Music Library Organization

Directory Structure

Beets organizes music with customizable naming schemes. Default structure:

/music/library/
├── Artist Name/
│   ├── Album Name/
│   │   ├── 01 - Song Title.mp3
│   │   ├── 02 - Song Title.mp3
│   │   └── cover.jpg
│   └── Another Album/
│       └── ...
└── Another Artist/
    └── ...

Custom Organization

Customize the organization pattern in config.yaml:

paths:
  default: $albumartist/$album%aunique/$track $title
  singleton: Non-Album/$artist/$title
  comp: Compilations/$album%aunique/$track $title

Backing Up Your Music Library and Database

Persistent Volume Backups

Regular backups are essential for your music collection:

  1. Via Klutch.sh Volume Snapshots

    • Use your cloud provider’s volume snapshot feature
    • Schedule regular snapshots of both /music/library and /app/config volumes

  2. Manual Database Backup

    • Export the Beets database regularly
    • Backup the configuration files

Backup Procedures

Terminal window
# Backup Beets database
sqlite3 /app/config/library.db ".backup /app/config/library-backup.db"


# Create a tarball of configuration
tar -czf beets-config-backup.tar.gz /app/config/


# Create a tarball of music library (large operation)
tar -czf music-library-backup.tar.gz /music/library/

Database Setup and Migration

Beets Database

Beets uses SQLite by default for storing metadata. The database is stored at:

/app/config/library.db

Backing Up and Restoring

Terminal window
# Backup the database
sqlite3 /app/config/library.db ".backup /backup/library.db"


# Restore from backup
sqlite3 /app/config/library.db ".restore /backup/library.db"


# Export database to SQL
sqlite3 /app/config/library.db ".dump" > library-export.sql

Scaling and Performance

Vertical Scaling

For larger music libraries (100,000+ songs):

  1. Navigate to your app settings in Klutch.sh
  2. Increase instance resources:
    • Minimum 2 CPU cores
    • Minimum 2GB RAM
  3. Increase volume sizes to accommodate library growth

Performance Optimization

For large libraries, optimize configuration:

import:
  auto_update_cache: yes
  resume: ask
  duplicate_resolution: skip


musicbrainz:
  rate_limit_interval: 1.0    # Slow down API requests to avoid timeouts

Database Optimization

Terminal window
# Rebuild the database index
beet library-rebuild


# Clear the MusicBrainz cache
beet mb-reset

Custom Domain Configuration

To use your own domain with Beets:

  1. Navigate to your app’s “Domains” section in Klutch.sh
  2. Click “Add Custom Domain”
  3. Enter your domain (e.g., music.yourdomain.com)
  4. Configure your DNS provider with a CNAME record: 
    music.yourdomain.com → example-app.klutch.sh
  5. Klutch.sh automatically provisions SSL certificates

Advanced Plugins and Extensions

Installing Additional Plugins

Add plugins to your requirements.txt:

beets
beets-yearfolder
beets-alternatives
beets-copyartifacts
beets-inline

Update your Dockerfile to install from requirements:

COPY requirements.txt /app/
RUN pip install --no-cache-dir -r /app/requirements.txt
  • yearfolder: Organize albums by year
  • alternatives: Maintain multiple copies of files in different formats
  • copyartifacts: Copy non-music files (artwork, lyrics) with imports
  • inline: Dynamically modify metadata during import
  • replaygain: Calculate ReplayGain tags
  • acousticbrainz: Download AcoustBrainz tags for audio analysis

Security Best Practices

Authentication and Access Control

  • Restrict access to your Beets instance with a reverse proxy if needed
  • Use strong passwords if authentication is enabled
  • Keep API keys secure in environment variables
  • Never commit sensitive information to your repository

Network Security

  • Always use HTTPS (Klutch.sh provides this automatically)
  • Limit API access if exposing to the internet
  • Monitor access logs for unauthorized activity
  • Keep Beets and dependencies updated

Data Privacy

  • Your music collection stays on your server
  • No automatic phone-home or telemetry
  • Full control over metadata sources used
  • Regular backups ensure data resilience

Troubleshooting

Common Issues and Solutions

Issue: Web interface not accessible

Check that:

  • Port 8337 is correctly configured
  • Container is running (check logs in Klutch.sh dashboard)
  • Network configuration is set to HTTP traffic type

Issue: Music files not appearing in library

Solutions:

  • Ensure music files are in /music/library directory
  • Verify file formats are supported (MP3, FLAC, OGG, M4A)
  • Check import logs: cat /app/logs/import.log
  • Run manual import: beet import /music/incoming

Issue: Slow metadata fetching

Causes and solutions:

  • Adjust MUSICBRAINZ_RATE_LIMIT to slow down API requests
  • Increase instance resources
  • Clear MusicBrainz cache: beet mb-reset
  • Check network connectivity

Issue: Database corruption

Recovery steps:

  • Restore from backup: sqlite3 /app/config/library.db ".restore /backup/library.db"
  • Rebuild database: beet library-rebuild
  • Reimport music if necessary

Issue: Disk space issues

Solutions:

  • Check volume usage in Klutch.sh dashboard
  • Increase persistent volume size
  • Remove old import logs: rm /app/logs/*.log
  • Archive old media if needed

Upgrading Beets

To update Beets to a newer version:

  1. Update your Dockerfile: 
    RUN pip install --no-cache-dir --upgrade beets
  2. Commit and push to GitHub
  3. Klutch.sh will automatically rebuild with the latest version
  4. Test the updated version thoroughly

Advanced Configuration

Custom Metadata Processing

import:
  autotag: yes
  write: yes
  move: yes


match:
  strong_rec_thresh: 0.10
  medium_rec_thresh: 0.25
  weak_rec_thresh: 0.50
  max_rec: 0.95

Integration with Other Services

Export music metadata to other systems:

plugins:
  - web
  - export


export:
  json: yes
  csv: yes

Custom Import Behavior

import:
  resume: ask
  incremental: yes
  incremental_skip_later: yes
  from_scratch: no

Additional Resources

Conclusion

Deploying Beets on Klutch.sh provides you with a powerful, self-hosted music library management system that keeps your entire music collection organized, searchable, and properly tagged. With persistent storage for your music files and metadata, advanced tagging capabilities, and an intuitive web interface, Beets transforms the way you manage and enjoy your music. Klutch.sh’s managed infrastructure ensures your music library is always available, secure, and performant.

Start organizing your music collection today by deploying Beets on Klutch.sh and experience the benefits of a properly curated music library.