Yooooomi/your_spotify: two containers, four required variables and a 24 hour window
Self hosted Spotify tracking dashboard
At a glance
- What is it?
- A self hosted listening dashboard built as a server and client container pair, where the interesting decisions are the OAuth redirect URI, the import cache size and the two origin controls that most deployments never touch.
- Who is it for?
- It fits a household that wants its own dashboard and is willing to register a Spotify application, wire a redirect URI and accept that history older than 24 hours has to be imported with the cache tuned. Read the FRAME_ANCESTORS value before exposing it to a network you care about, keep PORT at 8080 when running under Docker, and expect the local install path to be the awkward one, since the README labels it not recommended.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 128 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- Yooooomi/your_spotify4,631 ★ · +58
| Repository | 2026-09-11 | 2026-11-15 |
|---|---|---|
| Yooooomi/your_spotify | 4.6k | 4.6k |
58 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Two containers and a compose file that declares your public URL
The application is split in two: a web server that polls the Spotify API every now and then, and a web application you use to explore the statistics. In the published compose example those are the server and web services, each with restart set to always, the server on port 8080 and the client on port 3000, and the server both linked to and dependent on a mongo service. The credentials live only on the server side. The comment on API_ENDPOINT is the load bearing line in the whole file, because that value has to appear in the Spotify dashboard as a valid URL, which is how the redirect URI check works later.
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_ENDYour own Spotify application decides where users come back to
Three prerequisites sit above the install: you own a Spotify application ID created in the Spotify developer dashboard, you hand both the public and the secret key to the server environment, and you register an authorized redirect URI. The creation walkthrough is eight steps, of which two carry the real configuration. The redirect URI is your server location on the internet or on your local network with the suffix /oauth/spotify/callback appended, with the examples given as http://localhost:8080/oauth/spotify/callback and http://home.mydomain.com/your_spotify_backend/oauth/spotify/callback. If you run the linuxserver image instead of the published one, the suffix changes to /api/oauth/spotify/callback, so the image you pick decides the string you register. The keys then go into the compose file as SPOTIFY_PUBLIC and SPOTIFY_SECRET.
Access is closed by default because users must be registered
Creating the Spotify application is only half of it, because Spotify expects the owner of an application to say who may use it. Anyone signing in to YourSpotify needs an account that has been entered in the Spotify dashboard first, under User Management, with a name and the email address the Spotify account was created with. The account that created the application does not have to be added. Registering people one at a time is the documented path, and the dashboard also offers a Request extension if you would rather not add users by hand, which is the option that matters for a shared family instance where several addresses change over time. The practical consequence is that a fresh install with new keys does not let anybody other than the application's creator in until that list is filled.
Four variables are required and the rest have defaults that assume compose
The environment table separates what you must supply from what you can leave alone. CLIENT_ENDPOINT, API_ENDPOINT, SPOTIFY_PUBLIC and SPOTIFY_SECRET are the four required keys. Among the defaults, TIMEZONE is Europe/Paris and affects read requests only, because the data itself is stored in UTC. MONGO_ENDPOINT defaults to mongodb://mongo:27017/your_spotify, where mongo is the name of the service in the compose file, so a differently named database service breaks the default rather than the app. PORT defaults to 8080 and is explicitly marked as one not to modify under Docker, since the compose file maps 8080 to 8080. MONGO_NO_ADMIN_RIGHTS exists as an opt out of asking for admin rights on the database, LOG_LEVEL defaults to info with debug called out for bug hunting, and the two Prometheus credentials are left undefined, so the metrics endpoint has no basic auth until you set them.
The import cache is a memory for request budget trade
Once registered, the dashboard retrieves data for the past 24 hours only, and the README calls that a technical limitation rather than a setting. Older history comes from two import methods, and both go through the same mechanism: a cache that limits how many requests are sent to the Spotify API during an import. The cache size is unlimited by default, controlled by MAX_IMPORT_CACHE_SIZE on the server, and the reasoning is spelled out directly: more cached elements means fewer requests to Spotify, which results in faster imports. So the knob is a straight trade between resident memory and API call volume, with no default ceiling. The privacy data method is documented as taking a maximum of 5 days, and the table of contents marks a full privacy data variant as the recommended one.
CORS defaults to your client endpoint, FRAME_ANCESTORS defaults to nothing
The two origin controls are separate and easy to confuse. CORS is not defined by default and simply falls back to CLIENT_ENDPOINT, and the documentation states that manual configuration is not required for typical deployments, adding that 99.9% of users do not need to touch it because it is handled automatically. When one backend serves several frontends, the value is a comma separated origin list, with origin1,origin2 given as the example of allowing both. FRAME_ANCESTORS is the other control and it has no default at all: it is a comma separated list of sites allowed to frame the website, and the table even names the value to use when you want every site allowed. Read that row before copying it. Two separate lists means a deployment can be locked down for framing while staying open for cross origin requests, or the reverse.
The local install path is labelled not recommended
Docker is presented first and the alternative carries its own warning in the heading, with the steps in LOCAL_INSTALL.md and a note that you still have to do the Spotify application work afterwards. The build surface shows what a monorepo deployment costs: three compose files for example, dev and production, three shell scripts for build, dev and prod, and four Dockerfiles, one each for client and server in a plain and a production variant. JavaScript dependencies are managed with pnpm rather than npm, through pnpm-workspace.yaml and pnpm-lock.yaml, and the repository carries a monorepo.code-workspace file for editor workspaces. The Prometheus credentials are documented as living under the server app directory, so the metrics surface is part of the server app rather than a sidecar, which is worth knowing before you expose that app publicly.
Version 1.20.1 in the tree sits past the 1.20.0 tag
The root package manifest is private, scoped as the your_spotify root package, and carries version 1.20.1 with the repository pointing at the GitHub origin and a single named author. The published releases stop at 1.20.0 on 2026-05-24, preceded by 1.19.0 on 2026-03-30 and 1.18.0 on 2026-02-24, so the tree is one patch ahead of any tag you can pull, which is normal for a private root manifest but means the version in the repository is not a release identifier. The last push to master was on 2026-07-10, later than all three releases. Licensing is GPL-3.0, with the license file at the root, and there is no separate homepage field.
Editorial conclusion
It fits a household that wants its own dashboard and is willing to register a Spotify application, wire a redirect URI and accept that history older than 24 hours has to be imported with the cache tuned. Read the FRAME_ANCESTORS value before exposing it to a network you care about, keep PORT at 8080 when running under Docker, and expect the local install path to be the awkward one, since the README labels it not recommended.
Frequently asked questions
How do you access your Spotify through this dashboard?
You create your own Spotify application in the developer dashboard, give the server both the public and the secret key as SPOTIFY_PUBLIC and SPOTIFY_SECRET, and register a redirect URI made of your server address plus /oauth/spotify/callback. Only accounts added under User Management in the Spotify dashboard can sign in.
What is your Spotify URL?
There is no single hosted address, since the dashboard is served from your own deployment. The client listens on port 3000 and the server on port 8080, and the URL registered in the Spotify dashboard is the server address with the callback suffix appended.
how to access your spotify wrapped
After registering, the dashboard retrieves data for the past 24 hours only, which the README calls a technical limitation. History older than that has to come from one of the two import methods, and the shorter privacy data method takes a maximum of 5 days.
your spotify alternative
The deployment options the README describes are hosting the server and client containers through compose, installing locally, which is marked not recommended, and running the linuxserver image, which changes the callback suffix to /api/oauth/spotify/callback.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/yooooomi-your-spotify)Star history chart for your README
[](https://hysenlabs.com/projects/yooooomi-your-spotify)Was this useful?