musicbrainz-docker: a full MusicBrainz mirror with search and replication

What the project actually runs, and what it mirrors

The repository contains everything needed to run a MusicBrainz mirror server with search and replication in Docker. The table of contents is long because there are four separate services and a fair amount of setup, and the list names them: the MusicBrainz Server itself, a Postgres database, a Solr search server, a Search Index Rebuilder for the search indexes, and replication from the upstream database. The description also says the project is about installing a mirror server with locally indexed search and automatically replicated data, which is a different thing from a read-only dump. The homepage points at the MusicBrainz Server setup documentation, and the README explicitly links out to Docker's own getting started and Compose documentation, which is a signal that the project assumes you already know the container tooling.

The resource numbers, and the smaller configuration if you drop search

The recommended hardware is given in three figures, and each has a lower alternative for a reason. The CPU is 16 threads, or 2 without indexed search, on x86-64 architecture. Memory is 16GB, or 4GB without indexed search. Disk space is 350GB, or 100GB without indexed search. The pattern is consistent across the three, and it tells you that the search index is the expensive part, not the database. That matters for planning, because a developer who only needs to query the relational data can run the whole thing on a small machine, and the README gives separate instructions for mirroring the Postgres database only, with neither the website nor the web API. The alternative is a separate compose override file, and the README is careful to note that you have to run the configure command first, as a first step, or it will blank out the configuration.

Getting the stack up, in the order the README gives

The install sequence is a specific order, and each step assumes the previous one. You clone the repository and change into it.

git clone https://github.com/metabrainz/musicbrainz-docker.git
cd musicbrainz-docker

Then you build the Docker images for the composed services once.

docker compose build

Next you create the database, which downloads the latest full data dumps.

docker compose run --rm musicbrainz createdb.sh -fetch

Then you start the website, which becomes available on port 5000.

docker compose up -d

At that point the local website shows data loaded from the dumps only, and the README says to keep going for indexed search and replication. There is one optional step in between, which is building the denormalized tables the server uses in production to speed up certain pages, and duplicating primary table data costs several extra gigabytes of space. Without them the server falls back to slower queries.

Search indexes: build them yourself or download them

The indexer step has two routes, and the choice is a trade of CPU and RAM against bandwidth. You can build the indexes manually from the installed database with a reindex command inside the indexer service, and the README notes this option is known to take four and a half hours with 16 CPU threads and 16GB of RAM. You can also index individual entity types rather than everything at once, adding the entity type flag for each, for example artist and release. Or you can skip the work and download pre-built indexes based on the latest data dump, by bringing up the musicbrainz and search services and then fetching and loading the backup archives. Search indexes are updated asynchronously, so the README warns that some delay should be expected before results reflect recent changes. Both index routes need the memory settings adjusted first, since the Solr Java heap is 2GB by default and the database shared buffers are also 2GB.

The compose file, and the settings that decide how the server runs

The default compose file gives you the shape of the system. The db service is built from a prebuilt Postgres image and runs Postgres with 2GB of shared buffers and a 2GB shared memory size. The musicbrainz service is the web server, published on a configurable host address and port that default to 5000, and it depends on the database, the search service and a valkey service for caching. The indexer service is built from the sir directory and shares the Postgres environment file. A lot of the server's behaviour is driven by environment variables rather than by configuration files, including the base FTP and download URLs, the number of server processes which defaults to 10, the web server host and port, and a flag for proxy use. Volumes cover the Postgres data, the Solr data, the database dump and the Solr dump directories, with the Solr backup mount marked read only. The Compose file also carries the Postgres and Solr version pins that the components section of the README points at.

Version pins, the admin scripts, and a firewall warning

The components section pins every moving part, and the pins are overridable by environment variable where it matters. The current MusicBrainz branch is a dated tag, the database schema sequence is 31, Postgres is version 18 and can be changed with the POSTGRES_VERSION variable, the MB Solr search server is 4.1.0 with the MB_SOLR_VERSION variable, and the Search Index Rebuilder is 4.0.1. The repository also carries a set of helper scripts under an admin directory, run with GNU Bash 4 or higher, and the configuration step for a database-only mirror is one of those scripts. The required software list is short: Docker Compose 2 or higher, Git, Bash for the admin scripts, and Linux or macOS, with Windows explicitly not documented and Ubuntu via VirtualBox recommended instead. Two operational warnings are worth repeating. On Docker Desktop for macOS you may need to raise the container memory from the default 2GB, and if you manage your firewall with UFW you need to fix the Docker and UFW security flaw with the ufw-docker project or an equivalent.

Editorial conclusion

musicbrainz-docker fits a team that needs its own copy of the MusicBrainz database, for development, for a search service, or because it wants to run replication without depending on the public site. It does not fit a laptop with a modest disk, since the full setup is documented at 350GB of disk and 16GB of memory, and the reduced figures only apply if you skip indexed search. Verify first that the resources you have match the indexed or non-indexed figures, raise the Postgres shared buffers and the Solr heap before you create the database, and read the firewall note if you run UFW, because the Docker and UFW interaction is a known source of silent breakage.

Frequently asked questions

Official sources

1. Issues
2. metabrainz/musicbrainz-docker on GitHub
3. Project website
4. README
5. Releases