Yooooomi/your_spotify: Self-Hosted Spotify Statistics Dashboard

Yooooomi/your_spotify: Self-Hosted Spotify Statistics Dashboard

Streaming platforms collect extensive data on listening habits, yet rarely expose meaningful tools for users to analyze their own behavior. For developers and privacy-conscious music enthusiasts, this creates a frustrating gap: you own the listening history, but not the insights. Yooooomi/your_spotify bridges this divide by offering a self-hosted Spotify tracking dashboard that polls the Spotify API and renders personal statistics through a clean web interface—without third-party data retention or subscription lock-in.

This guide covers everything needed to evaluate, deploy, and operate your_spotify, from Docker^{↗ Bright Coding Blog} Compose configuration to historical data import. Whether you're building a personal analytics stack or exploring self-hosted alternatives to proprietary dashboards, the project provides a transparent, GPL-licensed foundation.

What is Yooooomi/your_spotify?

your_spotify is an open-source, self-hosted application maintained by Yooooomi that tracks Spotify listening activity and surfaces statistics through a dedicated web dashboard. The project is implemented in TypeScript and structured as a dual-component system: a polling server that interfaces with Spotify's Web API, and a client-side web application for data visualization and exploration.

With 4,478 GitHub stars and 203 forks, the project has achieved meaningful traction within the self-hosting and developer community. It is licensed under the GNU General Public License v3.0, ensuring derivative works remain open. The most recent commit as of this writing was July 10, 2026, indicating active maintenance.

The architectural separation between server and client is deliberate. The server handles OAuth authentication with Spotify, persists data to MongoDB, and exposes an API; the client consumes this API to render dashboards. This design supports flexible deployment topologies—local development, homelab setups, or reverse-proxied production environments—while keeping credential handling centralized and auditable.

For developers already operating containerized infrastructure, your_spotify fits naturally into existing Docker Compose or Kubernetes workflows. The project's explicit Docker-first documentation signals that containerization is the supported path, with local installation documented but marked "not recommended."

Key Features

API-Driven Data Collection
The server component polls Spotify's Web API at configurable intervals, automatically capturing listening sessions without manual intervention. This eliminates the need for browser extensions or client-side data extraction tools that break with UI changes.

Historical Data Import
Two import pathways accommodate users with existing Spotify histories. The privacy data method retrieves approximately one year of history via standard Spotify data exports, typically completing within five days of request. The full privacy data method—explicitly recommended by the maintainer—yields complete account history since creation, though Spotify's processing can take up to thirty days. Both methods ingest JSON exports directly through the web interface.

Timezone-Aware Statistics
Data storage uses UTC, but read operations respect configurable timezones. The TIMEZONE environment variable defaults to Europe/Paris for server-side rendering, while individual users can override this in settings. Device-local timezone governs song history display, separating computation context from presentation context.

Prometheus Metrics Endpoint
Optional basic-auth-protected Prometheus scraping is available via PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD variables. This enables integration with existing observability stacks for monitoring import health, API rate limit proximity, or application uptime.

Registration Controls
Administrators can disable new registrations through the settings interface, converting an open instance to single-user or closed-group operation without redeployment.

CORS Flexibility
While automatically handled for typical deployments, the CORS variable permits explicit multi-origin configurations for advanced setups—such as serving the client from a CDN or embedding statistics in external dashboards.

Use Cases

Personal Music Analytics Archive
Long-term Spotify users lose access to detailed listening history beyond the platform's limited "Wrapped" annual summaries. your_spotify creates a persistent, queryable archive with trends across arbitrary timespans—identifying seasonal listening patterns, genre shifts, or artist discovery velocities unavailable through native tools.

Privacy-Preserving Alternative to Cloud Analytics
Developers and security-conscious users who reject third-party services like Last.fm or Spotify's own profiling can retain full data custody. MongoDB runs locally or on self-managed infrastructure; no telemetry leaves the controlled environment except Spotify API calls necessary for metadata resolution.

Homelab Integration Project
For practitioners building comprehensive self-hosted service ecosystems, your_spotify complements media servers (Jellyfin, Plex), download orchestrators (Sonarr, Lidarr), and monitoring stacks (Grafana, Prometheus). The Docker Compose deployment aligns with [INTERNAL_LINK: self-hosted-media-stack] patterns common in homelab communities.

Quantified Self Data Source
Users engaged in personal data analysis can export or directly query MongoDB collections for correlation with other life-tracking datasets—sleep patterns, productivity metrics, or location history—to test hypotheses about music's relationship to other behaviors.

Family or Small-Group Sharing
With controlled registration and per-user timezone support, a single instance can serve household members or small teams who want collective insights without individual Spotify account analytics exposure.

Installation & Setup

The project provides explicit Docker Compose configuration as the primary deployment method. Reproduce the following from the official documentation without modification:

services:
  server:
    image: yooooomi/your_spotify_server
    restart: always
    ports:
      - "8080:8080"
    links:
      - mongo
    depends_on:
      - mongo
    environment:
      API_ENDPOINT: http://localhost:8080 # This MUST be included as a valid URL in the spotify dashboard (see below)
      CLIENT_ENDPOINT: http://localhost:3000
      SPOTIFY_PUBLIC: __your_spotify_client_id__
      SPOTIFY_SECRET: __your_spotify_secret__

  web:
    image: yooooomi/your_spotify_client
    restart: always
    ports:
      - "3000:3000"
    environment:
      API_ENDPOINT: http://localhost:8080

  mongo:
    container_name: mongo
    image: mongo:8
    volumes:
      - ./your_spotify_db:/data/db

Step 1: Create Spotify Application
Navigate to Spotify's developer dashboard, create an application, and configure the redirect URI. For the standard image, append /oauth/spotify/callback to your API_ENDPOINT; for the linuxserver variant, use /api/oauth/spotify/callback. Enable Web API access and register any non-creator users under User Management.

Step 2: Configure Environment Variables
Substitute __your_spotify_client_id__ and __your_spotify_secret__ with values from the Spotify application settings. Ensure API_ENDPOINT is reachable from client devices—localhost suffices for local testing but requires DNS or IP substitution for network access.

Step 3: Deploy Stack
Execute docker compose up -d in the directory containing your configuration file. The depends_on declaration ensures MongoDB initializes before the server attempts connections.

Step 4: Verify Connectivity
Access the client at CLIENT_ENDPOINT (default http://localhost:3000). If the web application reports inability to retrieve global preferences, verify network path and API_ENDPOINT reachability from the client device.

Real Code Examples

The Docker Compose configuration above constitutes the project's primary deployment artifact. Several environment variables merit explicit examination for production hardening:

# Server environment excerpt with security-relevant variables
environment:
  API_ENDPOINT: http://localhost:8080
  CLIENT_ENDPOINT: http://localhost:3000
  SPOTIFY_PUBLIC: __your_spotify_client_id__
  SPOTIFY_SECRET: __your_spotify_secret__
  COOKIE_VALIDITY_MS: 1h          # Authentication session duration using vercel/ms patterns
  CORS: "origin1,origin2"         # Only required for multi-origin deployments
  FRAME_ANCESTORS: "https://trusted.example.com"  # Clickjacking protection

The COOKIE_VALIDITY_MS variable accepts vercel/ms patterns—1h, 7d, 365d—for intuitive session configuration without millisecond arithmetic. The FRAME_ANCESTORS variable controls Content-Security-Policy frame-ancestors; the special value i-want-a-security-vulnerability-and-want-to-allow-all-frame-ancestors disables protection entirely, though the naming makes the risk explicit.

For Prometheus integration, the server exposes metrics with optional basic authentication:

environment:
  PROMETHEUS_USERNAME: metrics_scraper
  PROMETHEUS_PASSWORD: ${PROMETHEUS_PASSWORD}  # Inject via secrets mechanism in production

The README notes that Prometheus configuration details are expanded in the server subdirectory documentation. The project does not currently provide additional code examples beyond Docker Compose and environment variable references; this reflects the documentation's scope rather than a limitation in functionality.

Advanced Usage & Best Practices

Import Strategy
Request full privacy data immediately upon instance creation, even before Spotify delivers the export. The thirty-day processing window overlaps with initial usage, and importing at account creation minimizes duplicate detection edge cases noted in the documentation.

Cache Sizing for Bulk Imports
The MAX_IMPORT_CACHE_SIZE variable defaults to unlimited, which maximizes speed by minimizing Spotify API requests during import. For resource-constrained deployments or imports spanning many years, consider bounding this to prevent memory pressure—though the README provides no specific guidance on appropriate limits, suggesting empirical adjustment based on container metrics.

MongoDB Persistence
The compose file mounts ./your_spotify_db as a bind volume. For production, evaluate named volumes or external MongoDB clusters with backup automation. The MONGO_NO_ADMIN_RIGHTS variable (false by default) controls database privilege requirements; set to true only when using managed MongoDB services that restrict admin access.

Reverse Proxy Considerations
When serving behind nginx, Traefik, or similar, ensure the API_ENDPOINT and CLIENT_ENDPOINT reflect externally accessible URLs. Internal Docker networking names resolve within the compose network but fail for browser-origin requests and OAuth callbacks.

Log Level Tuning
Set LOG_LEVEL=debug temporarily when troubleshooting import failures or synchronization gaps. The FAQ identifies revoked Spotify access as a common cause of stalled synchronization—check this before investigating application-level issues.

Comparison with Alternatives

your_spotify occupies a distinct niche: users who reject SaaS data retention but lack interest in Last.fm's social graph or scrobbling protocol. The trade-off is explicit operational responsibility—MongoDB backups, certificate management, and Spotify API quota monitoring fall to the operator. For developers already running container platforms, this overhead is marginal; for users seeking zero-configuration solutions, SaaS alternatives remain more appropriate.

FAQ

What license covers your_spotify?
GNU General Public License v3.0. Derivative works and distributions must preserve source availability.

Can I run this without Docker?
Local installation is documented but explicitly "not recommended" by the maintainer. Docker Compose is the supported path.

Why did my song synchronization stop?
Most commonly, Spotify access was revoked. Use the Relog to Spotify button in settings to re-establish OAuth authorization.

How far back can I import listening history?
Full privacy data exports include complete account history since creation; standard privacy data is limited to approximately one year.

Is there a limit on registered users?
No hard limit is documented. Administrators can disable new registrations to cap instance membership.

Can I change my timezone after setup?
Yes. Individual users override server default timezones in personal settings; the server default is configurable via TIMEZONE variable.

What happens if an import fails?
Failed imports—due to server reboot or ten consecutive request failures—can be retried from settings. Clean failed imports to remove associated temporary files.

Conclusion

Yooooomi/your_spotify delivers precisely what its description promises: a self-hosted Spotify tracking dashboard with credible data ownership and flexible deployment options. For developers, DevOps^{↗ Bright Coding Blog} practitioners, and privacy-oriented users already operating container infrastructure, it integrates cleanly into existing stacks with minimal friction. The TypeScript codebase, active maintenance through mid-2026, and GPL licensing provide reasonable confidence in long-term viability.

The tool is best suited for individuals or small groups prioritizing data custody over convenience, particularly those with existing homelab or self-hosting practices. Users seeking turnkey cloud solutions or social music discovery features will find better fits elsewhere.

Ready to deploy? Clone the repository, review the docker-compose-example.yml, and create your Spotify application at the developer dashboard. For issues, feature requests, or contributions, open an issue at https://github.com/Yooooomi/your_spotify.