YourSpotify: a self-hosted listening dashboard for Spotify, installed with docker-compose

What YourSpotify tracks that the Spotify client does not show you

The Spotify client shows what you are playing now and some yearly summaries. YourSpotify takes a different route: it runs a web server that polls the Spotify API on a schedule, writes what it finds into a Mongo database, and serves a separate web application for exploring that stored data. The README describes it as "a self-hosted application that tracks what you listen and offers you a dashboard to explore statistics about it."

The audience is narrow and specific. You need to own a Spotify application ID, create it in Spotify's developer dashboard, and hand the public and secret keys to your own server. That registration step is not optional and it is not a formality, because Spotify restricts which accounts can authenticate against a development-mode application. The README notes that once the application exists, Spotify wants you to register the users who will access it, and that the account which created the application is exempt from that requirement. A single-user deployment therefore costs nothing extra; a household deployment means adding each listener under User Management.

The payoff is that the data lives in a database you can query directly, rather than in a yearly recap that appears on Spotify's schedule. If you want to know which artists you played in a particular month, or how your listening shifted after a change in routine, that is the question this project is built to answer.

The polling server, the Mongo store and the separate client

The architecture has three moving parts, and the docker-compose example makes them explicit. There is a server container built from the yooooomi/your_spotify_server image, a web container from yooooomi/your_spotify_client, and a mongo container from the official mongo:8 image. The server is the only component that talks to Spotify; the web container only needs to know where the API lives.

Data flow runs in one direction for ingestion and the other for reading. The server authenticates against Spotify using the application's public and secret keys, polls the API, and persists results to Mongo at the endpoint given by MONGO_ENDPOINT. The client then reads statistics through the server's API. The README is explicit that the TIMEZONE setting "only affects read requests since data is saved with UTC time," which is the right design: storage stays in UTC and the display layer handles the offset. If your stats look shifted by a few hours, that variable is the first place to look, not the database.

The two-container split also means the client is not a static bundle you can drop on any host. It needs API_ENDPOINT at runtime, and the server needs CLIENT_ENDPOINT so that CORS and the OAuth flow resolve correctly. The README states that manually configuring CORS is not required for typical deployments and that it defaults to CLIENT_ENDPOINT. That default is convenient until you put the client behind a different hostname, at which point the CORS variable becomes a comma-separated list you maintain by hand.

Installing YourSpotify with docker-compose and connecting a Spotify app

The README points at docker-compose-example.yml as the starting point. Copy it, then fill in the four required variables. The example below is the structure the README gives, with the placeholders left as they appear in the file.

services:
  server:
    image: yooooomi/your_spotify_server
    restart: always
    ports:
      - "8080:8080"
    environment:
      API_ENDPOINT: http://localhost:8080
      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:
    image: mongo:8
    volumes:
      - ./your_spotify_db:/data/db

The server listens on port 8080 and the client on 3000, and the README warns not to change PORT if you are using docker. The volume mount on the mongo service is what keeps your history across container restarts.

Before starting the stack you need the Spotify side. In the developer dashboard, create an app, then set the redirect URI to your server's address with the suffix /oauth/spotify/callback. The README gives http://localhost:8080/oauth/spotify/callback as one example. If you use the linuxserver image instead, the README says the suffix becomes /api/oauth/spotify/callback. Check Web API, accept the terms, then open Settings and copy the public and secret keys into SPOTIFY_PUBLIC and SPOTIFY_SECRET.

Bring the stack up and open the client in a browser.

docker compose -f docker-compose-example.yml up -d

You should reach a login screen that hands you off to Spotify for authorization. If the callback fails, the redirect URI in the Spotify dashboard does not match API_ENDPOINT plus the /oauth/spotify/callback suffix, which is the most common first-run error and the one the README spends the most words on.

Importing past listening history and the cache setting that governs it

A fresh install starts recording from the moment it is connected, which is a real limitation for anyone who wants years of data. The README addresses this with an import path built on Spotify's privacy data export, and it distinguishes between two methods: a partial privacy data export and what it calls the full privacy data, which it recommends. The repository does not document in the README what the partial export omits, so the difference between the two is something you have to determine from the import behavior itself.

The import is not free of rate limits. MAX_IMPORT_CACHE_SIZE controls how many elements the importer keeps in memory, and the README explains the trade-off directly: more cache means fewer requests to Spotify, which makes imports faster. The default is infinite, which sounds generous until you run it on a small VPS and the process grows while it works through a large export. Capping that value is the lever you have when an import is memory-hungry, at the cost of more API round trips.

The README also has a Troubleshoot subsection for imports, which is worth reading before you start one rather than after. It does not document rollback, so if an import writes data you did not want, the recovery path is your Mongo volume and whatever backup you took of it. Take that backup first.

Where YourSpotify is the wrong tool

If you want a stats page without maintaining infrastructure, this is the wrong project. You are running three containers, holding a Spotify client secret, and keeping a database alive. A hosted recap service asks nothing of you and gives you less control, and for many people that trade is correct.

The OAuth requirement is a harder constraint than it first appears. The redirect URI has to be reachable and registered in the Spotify dashboard. The README's own example uses localhost, which works for a single machine, but sharing the dashboard with anyone else means a real hostname and a real certificate. Behind a reverse proxy with a path prefix, you have to keep API_ENDPOINT, CLIENT_ENDPOINT and the registered redirect URI all consistent, and the README's example values will not carry over.

The project also assumes a Spotify account that can create a developer application. The README's note about registering users under User Management implies a development-mode app with a small allowlist. If you are trying to track listening for a large group, that model works against you. And if your listening happens across several services, YourSpotify only knows about Spotify, so it will never be the complete picture.

Finally, the documentation is thinner than the feature set. CORS, the Prometheus credentials, and the FRAME_ANCESTORS option are each covered in a line or two, and the local install path is explicitly labeled not recommended and pushed to a separate file. Deployments that diverge from the compose example will require reading the source.

How YourSpotify differs from the linuxserver image and from hosted recaps

The closest alternative in the same niche is the linuxserver image, docker-your_spotify. It packages the same application, but the README notes one concrete difference: the OAuth callback suffix is /api/oauth/spotify/callback rather than /oauth/spotify/callback. That single path difference is what breaks a redirect URI copied from one guide into the other, and it is the reason to pick one image and stay with it rather than mixing instructions.

The other comparison is the hosted yearly recap. A hosted recap gives you a curated summary with no setup and no data ownership. YourSpotify gives you a database, an API, and the ability to ask questions the recap never poses. The cost is operational: containers, a Mongo volume, a client secret, and an OAuth callback you have to keep working. Neither is better in the abstract. One is a product you consume; the other is a service you run.

On the operational side, the README exposes Prometheus basic auth through PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD, and links to a server-level document for the metrics endpoint. If you already run Prometheus, that is the integration point; if you do not, those variables stay undefined and cost you nothing.

Licence, maintenance and what an upgrade actually involves

YourSpotify is licensed under GPL-3.0. That matters if you plan to modify it and distribute the result, because the licence carries copyleft obligations; it does not restrict running it privately for yourself. This is a description of the licence identifier in the repository, not legal advice, and anyone shipping a modified version should read the full text in the LICENSE file.

On maintenance, the last push to the default branch was on 2026-07-10, and the most recent release listed is 1.20.0 from 2026-05-24, following 1.19.0 in March and 1.18.0 in February. The repository is not archived. The release cadence over those months is regular, and the root package.json carries version 1.20.1, one patch ahead of the last tagged release. There is no published end-of-life or support policy in the README, so upgrade timing is your call.

Upgrading is a container image pull rather than a source build, which keeps the cost low. The risk sits in the database. The compose example mounts ./your_spotify_db into the mongo container, so the data survives image changes, but the README does not document a migration procedure or a rollback path between versions. Snapshot the volume before pulling a new tag. The MONGO_NO_ADMIN_RIGHTS variable exists for deployments that cannot grant admin rights on the database, which suggests the schema setup is handled at startup; the README does not explain what happens when that setup cannot complete.

Editorial conclusion

Adopt YourSpotify if you want your listening history in a database you control and you are willing to register a Spotify developer application and keep its secret on your own host. Do not adopt it if you want a zero-setup stats page, if you cannot expose an HTTPS callback URL for the OAuth redirect, or if you expect the import to reconstruct years of history without a Spotify privacy export. Before committing, verify that your redirect URI matches the server path with the /oauth/spotify/callback suffix, that Mongo data is on a mounted volume, and that the TIMEZONE value matches how you read your own listening habits.

Frequently asked questions

Official sources

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