musicbrainz-docker

⚠️ Security Warning: The search service runs Solr 7 in standalone mode, which is vulnerable to privilege escalation (CVE-2025-24814). Solr should generally only be accessible to your own clients.

To publish ports for all services (including db, valkey, and search) to the host:

admin/configure add publishing-all-ports
docker compose up -d

If you are running a database-only mirror, use:

admin/configure add publishing-db-port
docker compose up -d

To customize the RAM allocated to db (Postgres) or search (Solr) services, create a custom compose file in local/compose/ and add it via admin/configure.

Example local/compose/memory-settings.yml to set 4GB for both:

services:
  db:
    command: postgres -c "shared_buffers=4GB"
  search:
    environment:
      - SOLR_HEAP=4g

To apply:

admin/configure add local/compose/memory-settings.yml
docker compose up -d

To run a small server with sample data for testing SQL queries or Web Service calls (instead of a full installation):

git clone https://github.com/metabrainz/musicbrainz-docker.git
cd musicbrainz-docker
admin/configure add musicbrainz-standalone
docker compose build
docker compose run --rm musicbrainz createdb.sh -sample -fetch
docker compose up -d

Key differences from full installation:

• Uses a sample data dump instead of full dumps.
• Runs in standalone mode instead of mirror mode.
• Replication is not applicable.

Rebuilding images (for updates or configuration changes) leaves old images on your disk. To reclaim space, you can prune unused Docker objects.

:warning: If you use Docker for other projects, docker system prune --all will remove all unused images across your entire Docker environment, not just this project.

Live indexing allows search indexes to update automatically as data changes. Warning: This feature is currently experimental and unstable.

To enable it:

1. Disable replication cron (if previously enabled):

   admin/configure rm replication-cron
   docker compose up -d

2. Set up the database schema for SIR indexing:

   admin/setup-sir install

3. Build/Update search indexes (if not already done).

4. Enable live indexing:

   admin/configure add live-indexing-search
   docker compose up -d

5. Re-enable replication cron (if you disabled it in step 1).

   admin/configure add replication-cron
   docker compose up -d

The admin/ directory contains helper scripts designed to be executed from the host machine. These scripts manage configuration, replication, and message queues. You can use the --help flag on any script to see available options.

Key scripts include:

• admin/configure: Used for configuration management (refer to Docker Compose overrides for details).
• admin/setup-sir: Used to enable live indexing.
• admin/purge-message-queues: Clears existing message queues.
• admin/set-replication-token: Used to enable replication.

admin/configure --help
admin/setup-sir --help
admin/purge-message-queues --help
admin/set-replication-token --help

To run a MusicBrainz mirror server with indexed search, the following resources are recommended:

Recommended Hardware (with indexed search):

• CPU: 16 threads (x86-64 architecture)
• RAM: 16 GB
• Disk Space: 350 GB

Note: If running without indexed search, requirements drop to 2 CPU threads, 4 GB RAM, and 100 GB disk space.

Required Software:

• Docker Compose 2 (or higher)
• Git
• GNU Bash 4 (or higher) utilities (required for admin/ helper scripts)
• Linux or macOS (Windows users should use Ubuntu via VirtualBox)

Important macOS Note: If using Docker Desktop, increase container memory in Preferences > Resources > Memory beyond the 2GB default.

You can customize the behavior of the MusicBrainz Docker deployment using environment variables, most conveniently by editing the .env file.

To verify the configuration values that will be passed to your containers, use:

docker compose config

To apply changes made to the .env file, restart the services with:

docker compose up -d

To recreate the database, run the recreatedb.sh script inside the musicbrainz container. You will be prompted for the Postgres password defined in default/postgres.env.

To fetch new data dumps immediately before recreating the database, use the -fetch flag.

# Standard recreation
docker compose run --rm musicbrainz recreatedb.sh

# Recreation with fetching new data dumps
docker compose run --rm musicbrainz recreatedb.sh -fetch

Solr development relies on schema changes in mb-solr and mmd-schema. To run a local version of mb-solr within the search service for integration testing:

1. Run build.sh from your mb-solr local working copy to build an image with a local tag.
2. Set MB_SOLR_VERSION in your .env file to that local tag.
3. Start the services:

   docker compose up -d