RompMusic

Self-Hosting Guide

Run RompMusic on your own Debian server or VPS using Docker. You need:

  • Docker and Docker Compose
  • Music files (MP3, FLAC, M4A, OGG)
  • Optional: beets for organization and tagging

Quick Start

  1. Clone the repo (use --recursive so submodules are included):
git clone --recursive https://github.com/rompmusic/rompmusic.git
cd rompmusic
  1. Copy the example env file and edit it (see Editing .env below):
cp .env.example .env
# Edit .env with your values, then:
docker compose up -d

The API server is exposed on port 8097 by default (mapped from 8080 inside the container). The web client and docs site run on ports 3003 and 3002 respectively if you start the full stack.

Editing .env

In the repo root, .env is used by Docker Compose. Set at least the following:

JWT_SECRET
Required. A random secret for signing auth tokens (e.g. openssl rand -hex 32).
MUSIC_PATH
Path on the host to your music library. Mounted read-only into the server container as /music. Example: /home/you/Music or ./music.
DB_PASSWORD
PostgreSQL password for the rompmusic user and database. Defaults to rompmusic if unset.
ADMIN_COOKIE_SECRET
Secret for admin-panel session cookies. Set to a random string in production.

For password reset and email verification, set SMTP_HOST, SMTP_USER, SMTP_PASSWORD, SMTP_FROM (and SMTP_PORT if not 587).

Last.fm and Beets (optional)

You can set Last.fm and beets options either in .env or in the admin web interface. The admin panel overrides or supplements env: go to your server URL, log in as admin, open Dashboard → Server Settings. There you’ll find API keys and library schedule options.

Last.fm API key

Last.fm powers “similar tracks,” recommendations, and artist images. The API key is free.

  • Get a key: Sign in at last.fm, then go to last.fm/api/account/create. Create an API account and copy the “API Key.”
  • Where to put it: Either set LASTFM_API_KEY=your-key in your .env file, or in the admin panel under Server Settings → API keys → Last.fm API key. If you set it in both places, the value stored in the admin panel is used.

Beets

Beets is a command-line music manager. RompMusic can run beet fetch-art to fetch album art into your library—on a schedule or once after each library scan.

  • Installing beets: Install beets where the RompMusic server runs (e.g. pip install beets or your distro’s package). The default Docker server image does not include beets; to use fetch-art from the server you can run beets on the host and point the server at that library, or add beets to a custom server image.
  • Configuring beets: Configure beets so its library path is the same as MUSIC_PATH (e.g. directory: /music in ~/.config/beets/config.yaml if the server runs in Docker and mounts music at /music).
  • In the admin panel: Under Server Settings you can set Beets fetch-art interval (hours) (e.g. 24 for daily; 0 to disable) and Run beets fetch-art after each library scan. The optional Beets API key field is for storing an API key used by some beets plugins (e.g. Last.fm); you can enter it there if your beets config needs it.

Create an admin user

After the stack is running, create the first admin user with the create_admin script. From the repo root, run:

docker compose exec server python -m rompmusic_server.scripts.create_admin

You will be prompted for username, email, and password. Then open the web admin panel at /server (e.g. https://music.yourdomain.com/server), log in with that admin account, and run a library scan so your music is indexed.

Connect the client

Point the client app at your server URL (e.g. https://music.yourdomain.com) and log in with your admin or invited user account. For step-by-step instructions (web app, Android, iOS, first-run server URL, and hosting the web client yourself), see the Client app setup guide.

Reverse proxy (nginx)

If you put nginx (or another reverse proxy) in front of the stack, proxy /api and /server to the backend, and /app/ to the web client. So that direct links and page reloads work, redirect client routes that omit the /app prefix to the app: /playlists, /history, /settings, and /album/*, /track/*, /artist/*, /playlist/* should redirect to /app/playlists, /app/album/..., etc. Otherwise those paths hit the website and return 404.

API reference

Once your server is running, the OpenAPI docs are available at /api/docs (Swagger) and /api/redoc (ReDoc)—e.g. rompmusic.com/api/docs. Use your own server URL when self-hosting.

← Back to home