EternalJukebox: hosting a working Infinite Jukebox on your own server

A fork that exists because the upstream stopped moving

EternalJukebox is a rehosting of the Infinite Jukebox, the web application that takes a song apart by its beats and stitches it together with other songs so the result never resolves. The repository states its reason for existing plainly: it is a fork that fixes bugs because the upstream repository is unmaintained.

That framing sets the expectations correctly. This is not a rewrite and it is not a new idea in the genre. It is maintenance of a specific, already built thing, and the value it offers is that it still runs when the original does not receive fixes. For a person who wants to understand the mechanism, the fork is close enough to the original to be legible, and the project is explicit that a hosted instance is available if you only want to use it rather than run it.

The stack is Java on the server with a static front end. The source tree shows a Gradle build, a src directory of Java code, a _web directory of Jekyll sources, a database directory, and Docker files for the containerised path. The licence is MIT, and the most recent published release is v1.0.1 from 2025-02-14, with the last push to the repository on 2026-06-10.

yt-dlp, ffmpeg, a Gradle jar and a Jekyll site

The Dockerfile shows the whole assembly line, and it is worth reading because it explains what the running service needs.

The first stage starts from amazoncorretto:11-alpine and installs the tools the service leans on: yt-dlp downloaded from its release page, then nodejs, npm, ffmpeg, gettext and python3 through apk. The second stage builds the server jar with Gradle 8 on JDK 11, running gradle clean shadowJar so the result is a fat jar with its dependencies bundled. The third stage builds the web pages with Jekyll, running jekyll build --source _web --destination web so the Jekyll sources in _web become a static site in web.

The final stage copies both outputs into the runtime image. The entry command is worth noting because it explains the config story: envsubst renders envvar_config.yaml into config.yaml, and only then does the container start the jar.

CMD envsubst < "/EternalJukebox/envvar_config.yaml" > "/EternalJukebox/config.yaml"\
    && java -jar EternalJukebox-all.jar

So the service reads a generated config file rather than reading environment variables directly for its own settings. Environment variables are the input to that generation step, which is the bridge between the Docker style setup and the plain file style manual setup.

The configuration is four environment variables and a file

The .env.example file in the repository root is the shortest complete description of what the service needs:

# only used for docker
PORT=

# Spotify Client / Secret; make an application over here: https://developer.spotify.com/my-applications/
SPOTIFYCLIENT=
SPOTIFYSECRET=

# This can be obtained from here: https://developers.google.com/youtube/v3/getting-started
YOUTUBE_API_KEY=

The comment above the Spotify pair is accurate: you create an application in the Spotify developer dashboard, and the client id and client secret it hands back are the two values the service wants. The YouTube Data API key comes from the Google developers site, and it is the key used for search and metadata rather than for downloading, since downloading is what yt-dlp is installed for.

Below that, the database block is commented out entirely, with SQL_USERNAME, SQL_PASSWORD, SQL_TYPE, SQL_HOST, SQL_PORT and SQL_DATABASE_NAME all present as inactive lines. The comment says the database setup can be left untouched if the database is not manually exposed, and the compose file in the repository root matches that intent by mounting a single H2 file, eternal_jukebox.mv.db, into the container.

The guide also mentions a config.yaml or config.json for the manual install, with config_template.yaml and config_template.json in the repository as starting points. It describes a variety of config options and says documentation for them is coming soon, which is the honest summary: the option names are discoverable in the templates, the explanations are not.

Running it with Docker Compose on port 8080

The install path that needs the least knowledge is Docker. You need docker and docker-compose installed, then you take .env.example, rename it to .env, and fill in the values. envvar_config.yaml also has to be present in the same folder, and the guide notes that you only need to edit it for advanced configuration.

With those three files in place, the compose file in the installation section is enough to get going without a separate database service:

version: "3"

services:
  main:
    image: daviirodrig/eternaljukebox
    ports:
      - 8080:8080
    env_file:
      - .env
    volumes:
      - "./envvar_config.yaml:/EternalJukebox/envvar_config.yaml"

Run docker compose up -d in the folder holding envvar_config.yaml, .env and docker-compose.yaml, and the guide says to stop it with docker compose down. The web interface is then reachable on the mapped port, 8080. Changing that is a one line edit to the ports entry, written in the guide as - <your port>:8080, which maps a host port of your choosing to the container's 8080.

The compose file checked into the repository is a superset of that snippet: it builds from the local source with build: ., tags the result eternaljukebox, sets restart: always, and mounts a data directory and the H2 database file in addition to the config. A MySQL service and an internal network are present but commented out, so the default deployment is the single container with a file-backed database.

Running the jar by hand and watching for port 11037

The manual install exists for anyone who would rather not run a container. Its prerequisites are a Java runtime, yt-dlp and ffmpeg. On Debian based systems the guide gives sudo apt-get install default-jre for Java and sudo apt-get install ffmpeg or equivalent for ffmpeg, and on Linux yt-dlp is fetched with curl into /usr/local/bin/yt-dlp and made executable with chmod a+rx.

Configuration is done by creating a file named config.yaml or config.json, with the note that YAML is easier to write but takes slightly more space. The Spotify and YouTube credentials go in there, in the same fields the .env file uses for the Docker route.

Starting it is one command from the folder holding the jar:

java -jar EternalJukebox.jar

If everything is right, the process prints a line telling you it is listening at http://0.0.0.0:11037, and you open http://localhost:11037 in a browser. The listening port in the manual path is therefore 11037, not the 8080 the container maps, which is a small difference that matters if you are writing a reverse proxy rule or a firewall exception.

The project files themselves come from a Jenkins job or a permanent server, and the guide notes the build is streamlined through Jenkins so the individual files or an all in one zip can be downloaded.

Building from source needs Gradle, a JDK and Jekyll

The build path is for advanced users only, and the guide says so directly. You need Gradle, a JDK, and Jekyll, and the project files from a git clone or an archive download.

The server build is a single command:

gradle clean shadowJar

Run from the project directory, it produces a jar in build/libs. The web pages are a second command, jekyll build --source _web --destination web, which turns the Jekyll sources into the static site that the jar serves.

Two details of the repository layout make this easier than the manual instructions suggest. There is a gradlew wrapper script and a gradlew.bat for Windows, so a Gradle install is not strictly required. And the Dockerfile performs exactly these two steps in separate stages, with the dependency-only copy in between so that Docker does not re-download dependencies on every source change, which is the pattern the comment at the top of that file describes as the reason for the stage split.

For day to day operation, though, the built image is the artifact that matters. The upgrade path the guide describes is to pull the newest published image and restart the stack.

What the fork leaves to you, and what to use instead

The honest limits of this project come from what it depends on. The service reaches YouTube through a Data API key and downloads audio with yt-dlp, and it resolves Spotify tracks with a client id and secret. A hosted instance therefore depends on two third party services staying reachable and on credentials that a single operator can revoke, and the fork fixes bugs in the jukebox code, not in that dependency chain. Anyone deploying this needs to make their own judgement about how their server uses the APIs, and that judgement is not something the documentation addresses.

There is also a documentation gap that matters in practice. The guide says the configuration options are documented soon, so the templates are the only reference for what can be tuned, and the default compose file comments out the MySQL path, meaning a MySQL deployment is a configuration exercise with no walkthrough.

As an alternative to hosting it yourself, the hosted instance at eternalbox.floriegl.tech does the same job with none of the server administration, and the upstream Infinite Jukebox remains the original reference for how the beat matching works, even though it is unmaintained. The difference in approach is ownership: the hosted instance gives you a working remix engine with someone else holding the credentials, while this fork gives you the code, the configuration templates and the ability to change the matching behaviour, at the cost of running a Java service and a media toolchain yourself.

Editorial conclusion

EternalJukebox fits anyone who wants the Infinite Jukebox remix behaviour under their own control, either to keep it alive after the upstream project stalled or to add a feature to it, and it is the wrong choice for anyone who just wants to listen, since a hosted instance already exists. Verify first that you can obtain a Spotify client id and secret and a YouTube Data API key, since the service will not start without them, and read the .env.example file before you deploy, because the option documentation is still listed as coming soon.

Frequently asked questions

Official sources

1. EternalBox/EternalJukebox on GitHub
2. License: MIT
3. Project website
4. README
5. Releases