Maloja Backup

This role backs up Maloja music scrobbling data using the Maloja API export feature.

ARA Ansible Bash Docker HTTPS JSON Maloja NAS

Maloja Backup Role

Overview

This role backs up Maloja music scrobbling data using the Maloja API export feature. It authenticates to the Maloja backend, downloads scrobble history as JSON, and stores it on dual NAS storage for redundancy. The role automatically manages retention by keeping only the last 5 backups per NAS.

Purpose

  • Data Protection: Backs up your complete music listening history
  • Migration Support: Export data for transferring to new Maloja instance
  • Disaster Recovery: Restore scrobble history after data loss
  • Dual Redundancy: Backs up to two separate NAS devices (Synology DS418 and Proxmox OMV)
  • API-Based: Uses Maloja’s native export API
  • Automated Cleanup: Keeps only the last 5 backups per NAS

Requirements

  • Ansible 2.9 or higher
  • Maloja server with backend authentication enabled
  • Backend credentials stored in Ansible Vault
  • NAS mount points must be accessible and writable
  • Network connectivity to Maloja server

What is Maloja?

Maloja is a self-hosted music scrobbling server (similar to Last.fm) that tracks your music listening history. It provides:

  • Scrobble tracking from various music players
  • Statistics and charts about your listening habits
  • API for exporting/importing scrobble data

Role Variables

Required Variables

VariableRequiredDescription
vault_maloja_backend_userYesMaloja backend username (stored in Ansible Vault)
vault_maloja_backend_passwordYesMaloja backend password (stored in Ansible Vault)

Optional Variables

VariableDefaultDescription
maloja_backup_urlhttps://server.homelabMaloja instance URL
maloja_backup_syno_mount_point/mnt/synology-ds418/maloja/exportSynology NAS backup destination
maloja_backup_prxmxomv_mount_point/mnt/prxmx-omv/maloja/exportProxmox OMV NAS backup destination
maloja_backup_nases_pathSee defaults/main.ymlList of destination paths with timestamps

Variable Details

vault_maloja_backend_user and vault_maloja_backend_password

Backend credentials for Maloja authentication. These are configured in Maloja’s settings and must be stored in Ansible Vault.

How to set up in Maloja:

  1. Access Maloja settings
  2. Navigate to Authentication section
  3. Set backend username and password
  4. Note: This is different from web UI login

Example vault variables:

vault_maloja_backend_user: "admin"
vault_maloja_backend_password: "YourSecurePassword123"

maloja_backup_url

The full URL to your Maloja instance. Must include protocol (https://).

Example:

maloja_backup_url: "https://scrobble.example.com"

Dependencies

This role has no dependencies on other Ansible roles, but requires:

  • Maloja server running and accessible
  • Backend authentication configured in Maloja
  • NAS mounts configured (see nas_mount or nas_mount_systemd roles)

Example Playbook

Basic Usage

---
- name: Backup Maloja Scrobble Data
  hosts: localhost
  become: true

  roles:
    - maloja_backup

With Custom Maloja URL

---
- name: Backup Maloja Data from Custom URL
  hosts: localhost
  become: true

  vars:
    maloja_backup_url: "https://music.example.com"

  roles:
    - maloja_backup

Scheduled Backup with Cron

---
- name: Schedule Weekly Maloja Backup
  hosts: localhost
  become: true

  tasks:
    - name: Create cron job for weekly Maloja backup
      ansible.builtin.cron:
        name: "Weekly Maloja Scrobbles Backup"
        minute: "0"
        hour: "4"
        weekday: "0"  # Sunday
        job: "ansible-playbook /path/to/maloja_backup.yml"

What This Role Does

  1. Ensures backup directories exist on both NAS mount points
  2. Authenticates to Maloja backend API (/auth/authenticate)
  3. Extracts session cookies from authentication response
  4. Downloads scrobble export using authenticated session (/apis/mlj_1/export)
  5. Saves export to both NAS locations with timestamped filename
  6. Finds all existing backups on each NAS
  7. Removes old backups, keeping only the 5 most recent per NAS

Authentication Flow

Step 1: Authenticate

POST /auth/authenticate
Body: {
  "user": "admin",
  "password": "password"
}

Response: HTTP 200/302/303 with session cookies

Step 2: Extract Cookies

The role extracts session cookies from the authentication response for use in subsequent requests.

Step 3: Download Export

GET /apis/mlj_1/export
Headers:
  Cookie: {session_cookies}

Response: JSON file containing all scrobble data

Backup Format

The backup is a JSON file containing all scrobble data:

File Naming

maloja_export_YYYYMMDD_HHMMSS.json

Examples:

  • maloja_export_20260107_143022.json
  • maloja_export_20260107_190530.json

Note: Uses underscore instead of ‘T’ for better readability.

JSON Content Structure

{
  "scrobbles": [
    {
      "time": 1704642000,
      "artists": ["Artist Name"],
      "title": "Song Title",
      "album": "Album Name",
      "duration": 240
    },
    {
      "time": 1704645600,
      "artists": ["Another Artist"],
      "title": "Another Song",
      "album": "Another Album",
      "duration": 180
    }
  ]
}

Data includes:

  • Timestamp of each scrobble (Unix epoch)
  • Artist names (supports multiple artists)
  • Track titles
  • Album names
  • Track duration (if available)

Backup Content

The backup includes:

  • All scrobbles (complete listening history)
  • Artist information
  • Track titles and albums
  • Timestamps for each scrobble
  • Duration data (if available)

The backup does NOT include:

  • Maloja configuration settings
  • User accounts/passwords
  • Custom rules or filters
  • Statistics cache (regenerated from scrobbles)

Backup Retention

The role implements automatic retention management:

  • Keeps: Last 5 backups per NAS
  • Deletes: Backups older than the 5th most recent
  • Per-NAS logic: Each NAS independently maintains 5 backups

This ensures you have:

  • 5 backups on Synology DS418
  • 5 backups on Proxmox OMV
  • Total: Up to 10 backup copies across both devices

Restoration

To restore from a backup, use the companion maloja_import_backup role or manually:

Via Maloja Web UI

  1. Access Maloja settings
  2. Navigate to Import section
  3. Upload the JSON export file
  4. Click “Import”

Via API

curl -X POST -F "file=@maloja_export_20260107_143022.json" \
  "https://server.homelab/apis/mlj_1/import"

Security Considerations

  • Credential Protection: Backend credentials marked with no_log: true
  • Vault Storage: Credentials must be in Ansible Vault
  • Session Cookies: Marked with no_log: true to prevent exposure
  • HTTPS Required: Always use HTTPS for Maloja connections
  • File Permissions: Backup files created with mode 0644

Tags

This role does not define any tags. Use playbook-level tags if needed:

- hosts: localhost
  roles:
    - maloja_backup
  tags:
    - backup
    - maloja
    - music
    - scrobbles

Notes

  • Authentication accepts HTTP status codes 200, 302, and 303 (all valid responses)
  • Session cookies are extracted and used for subsequent requests
  • Export downloads the complete scrobble history (can be large for long-time users)
  • JSON format is Maloja-specific and compatible with Maloja import

Troubleshooting

”Authentication failed” errors

Verify backend credentials:

  • Check credentials are correct in Maloja settings
  • Ensure vault_maloja_backend_user and vault_maloja_backend_password are set
  • Test manually: curl -X POST -d '{"user":"admin","password":"pass"}' https://server.homelab/auth/authenticate

”No cookies_string in response”

This means authentication didn’t return session cookies:

  • Check Maloja is configured for backend authentication
  • Verify Maloja version supports backend auth (v2.0+)
  • Check Maloja logs for authentication errors

”Permission denied” when writing to NAS

Ensure:

  • NAS is mounted: mount | grep synology
  • Backup directories exist and are writable
  • User has write permissions

”Connection refused” errors

Verify:

  • Maloja is running: Check Docker container or service status
  • URL is correct: curl -I https://server.homelab
  • Network connectivity from Ansible host to Maloja

Export file is empty or very small

Check:

  • Maloja has scrobble data (view in web UI)
  • API export endpoint is accessible
  • Session authentication is working

Performance Considerations

  • Export size depends on scrobble history (typically 1KB per 10-15 scrobbles)
  • Large histories (100,000+ scrobbles) may take 10-30 seconds to export
  • Network transfer time depends on NAS speed

Typical file sizes:

  • 1 year of active scrobbling: ~500KB - 2MB
  • 5 years of active scrobbling: ~2MB - 10MB
  • 10 years of active scrobbling: ~5MB - 20MB

Maloja Version Compatibility

  • Maloja 2.0+: Full support (backend authentication)
  • Maloja 3.0+: Full support
  • Earlier versions: May require different authentication method

API Endpoints Used

1. Authenticate

POST /auth/authenticate
Content-Type: application/json

Body:
{
  "user": "backend_user",
  "password": "backend_password"
}

2. Export Scrobbles

GET /apis/mlj_1/export
Cookie: {session_cookies}
  • maloja_import_backup: Imports scrobble data from backups created by this role

Alternative: Manual Backup

If you prefer manual backup:

# Authenticate and get cookies
COOKIES=$(curl -s -c - -X POST \
  -H "Content-Type: application/json" \
  -d '{"user":"admin","password":"pass"}' \
  https://server.homelab/auth/authenticate | grep -oP 'session\t\K.*')

# Download export
curl -o maloja_export_$(date +%Y%m%d_%H%M%S).json \
  -H "Cookie: session=$COOKIES" \
  https://server.homelab/apis/mlj_1/export

Best Practices

  1. Schedule regular backups (weekly recommended for active users)
  2. Verify backup size occasionally to ensure data is being exported
  3. Test restoration periodically to verify backup integrity
  4. Keep multiple versions (the role keeps 5 per NAS)
  5. Store offsite if music listening data is important to you

License

MIT

Author

Created for homelab infrastructure management.