YourSpotify: A Self-Hosted Spotify Listening Dashboard Built on Polling and Mongo

The Problem YourSpotify Solves, and Who Actually Has It

Spotify's own apps show you a wrapped summary once a year and a recently played list that rolls off quickly. If you want to know which tracks you played in March, or how your listening changed after a specific album came out, the client does not answer that. YourSpotify exists to close that gap: the README describes it as a self-hosted application that tracks what you listen to and offers a dashboard to explore statistics about it. The audience is narrow and specific. You need to own a Spotify application ID, created through Spotify's developer dashboard, and you need to supply that application's public and secret keys to the server. That means the project is aimed at people who are willing to register a developer app and run containers, not at casual listeners who want a sign-up link. The payoff is that the listening history lives in a MongoDB database you control, on a machine you control, and the queries run against your copy rather than against a vendor's API.

Two Processes, One Mongo, and a Polling Loop

The architecture is split in two. There is a web server, which per the README polls the Spotify API every now and then, and there is a web application where the statistics are displayed. In the reference docker-compose file these are separate images, yooooomi/your_spotify_server and yooooomi/your_spotify_client, plus a mongo service. The server holds the Spotify credentials and does the polling and OAuth callback handling; the client is the React front end that talks to the server through API_ENDPOINT. The database is the durable part: the compose example mounts ./your_spotify_db to /data/db so the history survives container restarts. One detail worth noting is the timezone handling. The TIMEZONE variable defaults to Europe/Paris, and the README states it only affects read requests, since data is saved with UTC time. That is the right design, but it also means a misconfigured timezone will shift your daily and monthly boundaries without corrupting stored data. If your charts look off by a few hours, TIMEZONE is the first key to check, not the database.

Getting It Running: The Compose File and the Required Keys

The README points at docker-compose-example.yml and lists four required environment values: CLIENT_ENDPOINT, API_ENDPOINT, SPOTIFY_PUBLIC and SPOTIFY_SECRET. Everything else has a default. The example sets API_ENDPOINT to http://localhost:8080 and CLIENT_ENDPOINT to http://localhost:3000, and the README warns that API_ENDPOINT must be included as a valid URL in the Spotify dashboard. Before any of this works you have to create a Spotify application, set its redirect URI to your server location with the suffix /oauth/spotify/callback, check Web API, and copy the public and secret keys into the compose file. The README also notes that Spotify requires you to register the users who will access the application, unless they are the account that created it, and that a Request extension option exists if you do not want to register users. That registration step is easy to miss and will present as an authentication failure rather than a configuration error. If you use the linuxserver image instead of the official one, the callback path changes to /api/oauth/spotify/callback.

Importing History and the Cache Size Trade-off

A fresh install starts with an empty database, so the README documents importing past history from Spotify privacy data, with a full privacy data option described as recommended. The import path is where the tuning knobs live. MAX_IMPORT_CACHE_SIZE defaults to infinite and controls the maximum number of elements held in the cache during an import; the README states that more cache means fewer requests to Spotify and therefore faster imports. That default is generous, and it is the setting most likely to hurt you on a small VPS. An unbounded cache during a large import is a memory commitment, and the README does not publish a figure for how much memory a given cache size consumes. If you are importing years of history on a container with a low memory limit, set MAX_IMPORT_CACHE_SIZE to a finite value before starting rather than after the process is killed. The same section links a troubleshoot note, which suggests imports are the part of the system that generates the most support traffic.

Where the Design Gets in Your Way

The dependency on a Spotify developer application is the sharpest constraint. Spotify caps how many users a development-mode application can authorize, and the README's answer is to register each user by email through User Management or request an extension. For a single person tracking their own listening, this is invisible. For a household or a small group, it becomes an administrative task that lives in Spotify's dashboard, not in YourSpotify. The polling model has a second consequence: the README does not state a polling interval, so there is no documented bound on how stale the data can be, and no documented rate-limit handling. The project also assumes MongoDB. There is no supported alternative store in the material, so backing up your listening history means backing up a Mongo volume, and MONGO_NO_ADMIN_RIGHTS exists for deployments where the database user cannot be granted admin rights. Finally, the README marks installing locally as not recommended, so the Docker path is the supported one whether or not you want containers.

Alternatives and the Actual Difference in Approach

The obvious comparison is Last.fm scrobbling, and the difference is architectural rather than cosmetic. A scrobbler pushes each play to a third-party service as it happens, and the history lives in that service's database under that service's terms. YourSpotify pulls from the Spotify API on a schedule and writes to your own MongoDB, which is why it needs your Spotify client secret and why the import step exists to backfill history the poller never saw. If you want zero infrastructure and do not mind the data living elsewhere, scrobbling is less work. If you want to run SQL-like queries over your own listening data, or keep it after you stop using a service, the self-hosted poller is the point. The other alternative is simply exporting your Spotify privacy data and analyzing the JSON yourself. That gives you a complete historical record with no server to maintain, but it is a snapshot rather than a live dashboard, and it will not update until you request another export.

Maintenance Cost and the GPL-3.0 Obligation

The release cadence visible in the repository is roughly every two months, with 1.20.0 in May 2026, 1.19.0 in March, and 1.18.0 in February, and the project is not archived. Upgrades mean pulling new images for the server and client and restarting the stack; the Mongo volume is separate and is the thing to back up before any upgrade that might touch the schema. There is no migration tooling described in the README, so a backup of ./your_spotify_db is your rollback plan. The licence is GPL-3.0. That matters if you intend to modify the code and distribute it: the GPL requires derivative distributions to carry the same licence and to make source available. Running it privately for yourself does not trigger distribution obligations. This is a description of the licence text, not legal advice; if you plan to fork and ship, read the licence or talk to someone qualified. The README also links a PayPal donation badge and a sponsoring section, so the project has no commercial support tier to fall back on.

Editorial conclusion

Adopt YourSpotify if you already run Docker Compose, are comfortable registering a Spotify developer application, and want listening history you control rather than a third-party stats site. Skip it if you need Spotify to authorize more than a handful of users without a quota extension, or if you want a hosted service with no MongoDB volume to back up. Verify first that your redirect URI matches the exact callback path your image expects (/oauth/spotify/callback for the official image, /api/oauth/spotify/callback for the linuxserver build), because a mismatch there is the failure you will hit before any dashboard loads.

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. Yooooomi/your_spotify on GitHub