{"id":13907680,"url":"https://github.com/metabrainz/musicbrainz-docker","last_synced_at":"2026-01-19T21:08:00.693Z","repository":{"id":14625061,"uuid":"20824421","full_name":"metabrainz/musicbrainz-docker","owner":"metabrainz","description":"Docker Compose project for the MusicBrainz Server with replication, search, and development setup","archived":false,"fork":false,"pushed_at":"2025-07-03T13:17:36.000Z","size":46800,"stargazers_count":381,"open_issues_count":23,"forks_count":96,"subscribers_count":20,"default_branch":"master","last_synced_at":"2025-07-18T08:31:04.240Z","etag":null,"topics":["docker","docker-compose","musicbrainz"],"latest_commit_sha":null,"homepage":"https://musicbrainz.org/doc/MusicBrainz_Server/Setup","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"jsturgis/musicbrainz-docker","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metabrainz.png","metadata":{"funding":{"custom":["https://metabrainz.org/donate"],"github":["metabrainz"]},"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-06-14T03:44:19.000Z","updated_at":"2025-07-17T12:20:16.000Z","dependencies_parsed_at":"2023-10-10T13:32:06.470Z","dependency_job_id":"d758a9ed-e558-4ee5-bd21-cc5769052c25","html_url":"https://github.com/metabrainz/musicbrainz-docker","commit_stats":null,"previous_names":[],"tags_count":102,"template":false,"template_full_name":null,"purl":"pkg:github/metabrainz/musicbrainz-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metabrainz%2Fmusicbrainz-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metabrainz%2Fmusicbrainz-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metabrainz%2Fmusicbrainz-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metabrainz%2Fmusicbrainz-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metabrainz","download_url":"https://codeload.github.com/metabrainz/musicbrainz-docker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metabrainz%2Fmusicbrainz-docker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267442904,"owners_count":24087893,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-compose","musicbrainz"],"created_at":"2024-08-06T23:02:05.334Z","updated_at":"2026-01-19T21:08:00.684Z","avatar_url":"https://github.com/metabrainz.png","language":"Shell","funding_links":["https://metabrainz.org/donate","https://github.com/sponsors/metabrainz"],"categories":["HarmonyOS","Shell"],"sub_categories":["Windows Manager"],"readme":"# MusicBrainz mirror server with search and replication\n\nThis repo contains everything needed to run a musicbrainz mirror server with\nsearch and replication in docker.\n\n## Table of contents\n\n\u003c!-- toc --\u003e\n\n* [Prerequisites](#prerequisites)\n  - [Recommended hardware/VM](#recommended-hardwarevm)\n  - [Required software](#required-software)\n  - [External documentation](#external-documentation)\n* [Components version](#components-version)\n* [Installation](#installation)\n  - [Build Docker images](#build-docker-images)\n  - [Create database](#create-database)\n  - [Build materialized tables](#build-materialized-tables)\n  - [Start website](#start-website)\n  - [Set up search indexes](#set-up-search-indexes)\n  - [Enable replication](#enable-replication)\n  - [Enable live indexing](#enable-live-indexing)\n* [Advanced configuration](#advanced-configuration)\n  - [Local changes](#local-changes)\n  - [Docker environment variables](#docker-environment-variables)\n  - [Docker Compose overrides](#docker-compose-overrides)\n* [Test setup](#test-setup)\n* [Development setup](#development-setup)\n  - [Local development of MusicBrainz Server](#local-development-of-musicbrainz-server)\n  - [Local development of Search Index Rebuilder](#local-development-of-search-index-rebuilder)\n  - [Local development of MusicBrainz Solr](#local-development-of-musicbrainz-solr)\n* [Helper scripts](#helper-scripts)\n  - [Recreate database](#recreate-database)\n  - [Recreate database with indexed search](#recreate-database-with-indexed-search)\n* [Update](#update)\n* [Cleanup](#cleanup)\n* [Removal](#removal)\n* [Issues](#issues)\n\n\u003c!-- tocstop --\u003e\n\n## Prerequisites\n\n### Recommended hardware/VM\n\n* CPU: 16 threads (or 2 without indexed search), x86-64 architecture\n* RAM: 16 GB (or 4 without indexed search)\n* Disk Space: 350 GB (or 100 without indexed search)\n\n### Required software\n\n* Docker Compose 2 (or higher), see [how to install Docker Compose](https://docs.docker.com/compose/install/)\n* Git\n* GNU Bash 4 (or higher) utilities, for [admin helper scripts](admin/) only\n  (On macOS, use [Homebrew](https://brew.sh/).)\n* Linux or macOS\n  (Windows is not documented yet, it is recommended to use Ubuntu via VirtualBox\n  instead.)\n\nIf you use Docker Desktop on macOS you may need to increase the amount of memory\navailable to containers from the default of 2GB:\n\n* Preferences \u003e Resources \u003e Memory\n\nIf you use Ubuntu 24.04 or later, the above requirements can be set up by running:\n\n```bash\nsudo apt-get update \u0026\u0026 \\\nsudo apt-get install docker.io docker-compose-v2 git \u0026\u0026 \\\nsudo systemctl enable --now docker.service\n```\n\nIf you use [UFW](https://help.ubuntu.com/community/UFW) to manage your firewall:\n\n* [ufw-docker](https://github.com/chaifeng/ufw-docker) or any other way to fix\n  the Docker and UFW security flaw.\n\n### External documentation\n\n* Introduction: [Getting started with Docker](https://docs.docker.com/get-started/)\n  and [Overview of Docker Compose](https://docs.docker.com/compose/)\n* Command-line: [`docker` CLI reference](https://docs.docker.com/engine/reference/commandline/docker/)\n  and [`docker compose` CLI reference](https://docs.docker.com/compose/reference/overview/)\n* Configuration: [Compose file version 3 reference](https://docs.docker.com/compose/compose-file/)\n\n## Components version\n\n* Current MB Branch: [v-2026-01-19.0](build/musicbrainz/Dockerfile#L98)\n* Current DB_SCHEMA_SEQUENCE: [30](build/musicbrainz/Dockerfile#L134)\n* Postgres Version: [16](docker-compose.yml)\n  (can be changed by setting the environment variable `POSTGRES_VERSION`)\n* MB Solr search server: [4.1.0](docker-compose.yml#L84)\n  (can be changed by setting the environment variable `MB_SOLR_VERSION`)\n* Search Index Rebuilder: [4.0.1](build/sir/Dockerfile#L38)\n\n## Installation\n\nThis section is about installing MusicBrainz mirror server\nwith locally indexed search and automatically replicated data.\n\nDownload this repository and change current working directory with:\n\n```bash\ngit clone https://github.com/metabrainz/musicbrainz-docker.git\ncd musicbrainz-docker\n```\n\nIf you want to mirror the Postgres database only (neither the website\nnor the web API), change the base configuration with the following\ncommand (as a first step, otherwise it will blank it out):\n\n```bash\nadmin/configure with alt-db-only-mirror\n```\n\n### Build Docker images\n\nDocker images for composed services should be built once using:\n\n```bash\ndocker compose build\n```\n\n### Create database\n\n:gear: Postgres shared buffers are set to 2GB by default.\nBefore running this step, you should consider [modifying your memory\nsettings](#modify-memory-settings) in order to give your database a\nsufficient amount of ram, otherwise your database could run very slowly.\n\nDownload latest full data dumps and create the database with:\n\n```bash\ndocker compose run --rm musicbrainz createdb.sh -fetch\n```\n\n\u003c!-- TODO: document available FTP servers --\u003e\n\u003c!-- TODO: document how to load local dumps --\u003e\n\n### Build materialized tables\n\nThis is an optional step.\n\nMusicBrainz Server makes use of materialized (or denormalized) tables in\nproduction to improve the performance of certain pages and features. These\ntables duplicate primary table data and can take up several additional gigabytes\nof space, so they're optional but recommended. If you don't populate these\ntables, the server will generally fall back to slower queries in their place.\n\nIf you wish to configure the materialized tables, you can run:\n\n```bash\ndocker compose run --rm musicbrainz bash -c 'carton exec -- ./admin/BuildMaterializedTables --database=MAINTENANCE all'\n```\n\n### Start website\n\nMake the local website available at \u003chttp://localhost:5000\u003e with:\n\n```bash\ndocker compose up -d\n```\n\nAt this point the local website will show data loaded from the dumps\nonly. For indexed search and replication, keep going!\n\n### Set up search indexes\n\n:information_source: Search indexes are updated asynchronously,\nsome delay can be experienced before getting updated results.\n\nDepending on your available ressources in CPU/RAM vs. bandwidth:\n\n* Either build search indexes manually from the installed database:\n\n  ```bash\n  docker compose exec indexer python -m sir reindex\n  ```\n\n  :gear: Java heap for Solr is set to 2GB by default.\n  Before running this step, you should consider [modifying your memory\n  settings](#modify-memory-settings) in order to give your search server a\n  sufficient amount of ram, otherwise your search server could run very slowly.\n\n  (This option is known to take 4½ hours with 16 CPU threads and 16 GB RAM.)\n\n  To index cores individually, rather than all at once, add `--entity-type CORE`\n  (any number of times) to the command above. For example `docker compose\n  exec indexer python -m sir reindex --entity-type artist --entity-type release`\n\n* Or download pre-built search indexes based on the latest data dump:\n\n  ```bash\n  docker compose up -d musicbrainz search\n  docker compose exec search fetch-backup-archives\n  docker compose exec search load-backup-archives\n  ```\n\n  (This option downloads 60 GB of Zstandard-compressed MB Solr backup archives.)\n\n  Once you are satisfied with the search results, you can drop the fetched archive files:\n\n  ```bash\n  docker compose exec search remove-backup-archives\n  ```\n\n:warning: Search indexes are not included in replication. You will have to\nrebuild search indexes regularly to keep it up-to-date. This can be done\nmanually with the commands above, with Live Indexing (see below), or with a\nscheduled cron job. Here's an example cron job that can be added to your\n`etc/crontab` file from your server's root:\n\n```crontab\n0 1 * * 7 YOUR_USER_NAME cd ~/musicbrainz-docker \u0026\u0026 /usr/bin/docker compose exec -T indexer python -m sir reindex\n```\n\nAt this point indexed search works on the local website/webservice.\nFor replication, keep going!\n\n### Enable replication\n\n#### Set replication token\n\nFirst, copy your MetaBrainz access token\n(see [instructions for generating a token](http://blog.metabrainz.org/2015/05/19/schema-change-release-2015-05-18-including-upgrade-instructions/))\nand paste when prompted to by the following command:\n\n```bash\nadmin/set-replication-token\n```\n\nThe token will be written to the file\n[`local`](local/)`/secrets/metabrainz_access_token`.\n\nThen, grant access to the token for replication with:\n\n```bash\nadmin/configure add replication-token\ndocker compose up -d\n```\n\n#### Run replication once\n\nRun replication script once to catch up with latest database updates:\n\n```bash\nbash -c 'docker compose exec musicbrainz replication.sh \u0026' \u0026\u0026 \\\ndocker compose exec musicbrainz /usr/bin/tail -f mirror.log\n```\n\n\u003c!-- TODO: estimate replication time per missing day --\u003e\n\n#### Schedule replication\n\nEnable replication as a cron job of `root` user in `musicbrainz`\nservice container with:\n\n```bash\nadmin/configure add replication-cron\ndocker compose up -d\n```\n\nBy default, it replicates data every day at 3 am UTC.\nTo change that, see [advanced configuration](#advanced-configuration).\n\nYou can view the replication log file while it is running with:\n\n```bash\ndocker compose exec musicbrainz tail --follow mirror.log\n```\n\nThe replication log file is sometimes renamed `mirror.log.1` after it is done.\n\n### Enable live indexing\n\n:warning: Search indexes’ live update for mirror server is **not stable** yet.\nUntil then, it should be considered as an experimental feature.\nDo not use it if you don't want to get your hands dirty.\n\n1. Disable [replication cron job](#schedule-replication) if you enabled it:\n\n   ```bash\n   admin/configure rm replication-cron\n   docker compose up -d\n   ```\n\n2. Make indexer goes through [AMQP\n   Setup](https://sir.readthedocs.io/en/latest/setup/index.html#amqp-setup)\n   with:\n\n   ```bash\n   docker compose exec indexer python -m sir amqp_setup\n   admin/create-amqp-extension\n   admin/setup-amqp-triggers install\n   ```\n\n3. [Build search indexes](#set-up-search-indexes) if they either have not been\n   built or are outdated.\n\n4. Make indexer watch reindex messages with:\n\n   ```bash\n   admin/configure add live-indexing-search\n   docker compose up -d\n   ```\n\n5. Reenable [replication cron job](#schedule-replication) if you disabled it at 1.\n\n   ```bash\n   admin/configure add replication-cron\n   docker compose up -d\n   ```\n\n## Advanced configuration\n\n### Local changes\n\nYou should **preferably not** locally change any file being tracked by git.\nCheck your working tree is clean with:\n\n```bash\ngit status\n```\n\nGit is set to ignore the followings you are encouraged to write to:\n\n* `.env` file,\n* any new file under [`local`](local/) directory.\n\n### Docker environment variables\n\nThere are many ways to set [environment variables in Docker\nCompose](https://docs.docker.com/compose/environment-variables/), the most\nconvenient here is probably to edit the hidden file `.env`.\n\nYou can then check values to be passed to containers using:\n\n```bash\ndocker compose config\n```\n\nFinally, make Compose picks up configuration changes with:\n\n```bash\ndocker compose up -d\n```\n\n#### Customize web server host:port\n\nBy default, the web server listens at \u003chttp://localhost:5000\u003e\n\nThis can be changed using the two Docker environment variables\n`MUSICBRAINZ_WEB_SERVER_HOST` and `MUSICBRAINZ_WEB_SERVER_PORT`.\n\nIf `MUSICBRAINZ_WEB_SERVER_PORT` set to `80` (http), then the\nport number will not appear in the base URL of the web server.\n\nIf set to `443` (https), then the port number will not appear either,\nbut the a separate reverse proxy is required to handle https correctly.\n\n#### Customize the number of processes for MusicBrainz Server\n\nBy default, MusicBrainz Server uses 10 `plackup` processes at once.\n\nThis number can be changed using the Docker environment variable\n`MUSICBRAINZ_SERVER_PROCESSES`.\n\n#### Customize download server\n\nBy default, data dumps and pre-built search indexes are downloaded from\nthe main download server. There is only one server currently available.\n\nFor development purposes, the download server can be changed using the\nDocker environment variable `MUSICBRAINZ_BASE_DOWNLOAD_URL`.\n\nFor backwards compatibility reasons an FTP server can be specified using the\n`MUSICBRAINZ_BASE_FTP_URL` Docker environment variable. Note that support for\nthis variable is deprecated and will be removed in a future release.\n\n#### Customize replication schedule\n\nBy default, there is no crontab file in `musicbrainz` service container.\n\nIf you followed the steps to [schedule replication](#schedule-replication),\nthen the crontab file used by `musicbrainz` service is bound to\n[`default/replication.cron`](default/replication.cron).\n\nThis can be changed by creating a custom crontab file under\n[`local/`](local/) directory,\n[and finally](https://docs.docker.com/storage/bind-mounts/#choose-the--v-or---mount-flag)\nsetting the Docker environment variable `MUSICBRAINZ_CRONTAB_PATH` to\nits path.\n\n#### Customize search indexer configuration\n\nBy default, the configuration file used by `indexer` service is bound\nto [`default/indexer.ini`](default/indexer.ini).\n\nThis can be changed by creating a custom configuration file under\n[`local/`](local/) directory,\n[and finally](https://docs.docker.com/storage/bind-mounts/#choose-the--v-or---mount-flag)\nsetting the Docker environment variable `SIR_CONFIG_PATH` to its path.\n\n#### Customize backend Postgres server\n\nBy default, the services `indexer` and `musicbrainz` are trying to connect to the host `db` (for both read-only and write host) but the hosts can\nbe customized using the `MUSICBRAINZ_POSTGRES_SERVER` and `MUSICBRAINZ_POSTGRES_READONLY_SERVER` environment variables.\n\nNotes:\n* After switching to another Postgres server:\n  * If not transferring data, it is needed to create the database again.\n  * For live indexing, the RabbitMQ server has to still be reachable from the Postgres server.\n* The helper script `create-amqp-extension` won’t work anymore.\n* The service `db` will still be up even if unused.\n\n#### Customize backend RabbitMQ server\n\nBy default, the services `db`, `indexer` and `musicbrainz` are trying to connect to the host `mq`\nbut the host can be customized using the `MUSICBRAINZ_RABBITMQ_SERVER` environment variable.\n\nNotes:\n* After switching to another RabbitMQ server:\n  - Live indexing requires to go through AMQP Setup again.\n  - If not transferring data, it might be needed to build search indexes again.\n* The helper script `purge-message-queues` won’t work anymore.\n* The service `mq` will still be up even if unused.\n\n#### Customize backend Redis server\n\nBy default, the service `musicbrainz` is trying to connect to the host `redis`\nbut the host can be customized using the `MUSICBRAINZ_REDIS_SERVER` environment variable.\n\nNotes:\n* After switching to another Redis server:\n  - If not transferring data, MusicBrainz user sessions will be reset.\n* The service `redis` will still be running even if unused.\n\n### Docker Compose overrides\n\nIn Docker Compose, it is possible to override the base configuration using\n[multiple Compose files](https://docs.docker.com/compose/extends/#multiple-compose-files).\n\nSome overrides are available under [`compose`](compose/) directory.\nFeel free to write your own overrides under [`local`](local/) directory.\n\nThe helper script [`admin/configure`](admin/configure) is able to:\n\n* **list** available compose files, with a descriptive summary\n* **show** the value of `COMPOSE_FILE` variable in Docker environment\n* set/update `COMPOSE_FILE` in `.env` file **with** a list of compose files\n* set/update `COMPOSE_FILE` in `.env` file with **add**ed or\n  **r**e**m**oved compose files\n\nTry `admin/configure help` for more information.\n\n#### Publish ports of all services\n\n:warning: The service `search` is currently running Solr 7 in\nstandalone mode which is vulnerable to privilege escalation.\nSee [CVE-2025-24814](https://lists.apache.org/thread/gl291pn8x9f9n52ys5l0pc0b6qtf0qw1) for details.\nWe are working on upgrading to Solr 9 in SolrCloud mode.\nSee [SEARCH-685](https://tickets.metabrainz.org/browse/SEARCH-685) for follow-up.\nIn general, Solr is strongly recommended to be accessible to your own clients only.\nSee [Solr Security](https://cwiki.apache.org/confluence/display/SOLR/SolrSecurity) for details.\nSimilarly, other services have not been configured to be safely publicly accessible either.\nTake this warning in consideration when publishing their ports.\n\nTo publish ports of services `db`, `mq`, `redis` and `search`\n(additionally to `musicbrainz`) on the host, simply run:\n\n```bash\nadmin/configure add publishing-all-ports\ndocker compose up -d\n```\n\nIf you are running a database only mirror, run this instead:\n\n```bash\nadmin/configure add publishing-db-port\ndocker compose up -d\n```\n\n#### Modify memory settings\n\nBy default, each of `db` and `search` services have about 2GB of RAM.\nYou may want to set more or less memory for any of these services,\ndepending on your available resources or on your priorities.\n\nFor example, to set 4GB to each of `db` and `search` services,\ncreate a file `local/compose/memory-settings.yml` as follows:\n\n```yaml\n# Description: Customize memory settings\n\nservices:\n  db:\n    command: postgres -c \"shared_buffers=4GB\" -c \"shared_preload_libraries=pg_amqp.so\"\n  search:\n    environment:\n      - SOLR_HEAP=4g\n```\n\nSee [`postgres`](https://www.postgresql.org/docs/current/app-postgres.html)\nfor more configuration parameters and options to pass to `db` service,\nand [`solr.in.sh`](https://github.com/apache/lucene-solr/blob/releases/lucene-solr/7.7.2/solr/bin/solr.in.sh)\nfor more environment variables to pass to `search` service,\n\nThen enable it by running:\n\n```bash\nadmin/configure add local/compose/memory-settings.yml\ndocker compose up -d\n```\n\n## Test setup\n\nIf you just need a small server with sample data to test your own SQL\nqueries and/or MusicBrainz Web Service calls, you can run the below\ncommands instead of following the above [installation](#installation):\n\n```bash\ngit clone https://github.com/metabrainz/musicbrainz-docker.git\ncd musicbrainz-docker\nadmin/configure add musicbrainz-standalone\ndocker compose build\ndocker compose run --rm musicbrainz createdb.sh -sample -fetch\ndocker compose up -d\n```\n\nThe two differences are:\n\n1. Sample data dump is downloaded instead of full data dumps,\n2. MusicBrainz Server runs in standalone mode instead of mirror mode.\n\n[Build search indexes](#set-up-search-indexes) and\n[Enable live indexing](#enable-live-indexing) are the same.\n\nReplication is not applicable to test setup.\n\n## Development setup\n\nRequired disk space is much lesser than normal setup: 15GB to be safe.\n\nThe below sections are optional depending on which service(s) you are coding.\n\n### Local development of MusicBrainz Server\n\nFor local development of MusicBrainz Server, you can run the below\ncommands instead of following the above [installation](#installation):\n\n```bash\ngit clone https://github.com/metabrainz/musicbrainz-server.git\nMUSICBRAINZ_SERVER_LOCAL_ROOT=$PWD/musicbrainz-server\ngit clone https://github.com/metabrainz/musicbrainz-docker.git\ncd musicbrainz-docker\necho MUSICBRAINZ_DOCKER_HOST_IPADDRCOL=127.0.0.1: \u003e\u003e .env\necho MUSICBRAINZ_SERVER_LOCAL_ROOT=\"$MUSICBRAINZ_SERVER_LOCAL_ROOT\" \u003e\u003e .env\nadmin/configure add musicbrainz-dev\ndocker compose build\ndocker compose run --rm musicbrainz createdb.sh -sample -fetch\ndocker compose up -d\n```\n\nThe main differences are:\n\n1. Sample data dump is downloaded instead of full data dumps,\n2. MusicBrainz Server runs in standalone mode instead of mirror mode,\n3. Development mode is enabled (but Catalyst debug),\n4. JavaScript and resources are automaticaly recompiled on file changes,\n5. MusicBrainz Server is automatically restarted on Perl file changes,\n6. MusicBrainz Server code is in `musicbrainz-server/` directory.\n7. Ports are published to the host only (through `MUSICBRAINZ_DOCKER_HOST_IPADDRCOL`)\n\nAfter changing code in `musicbrainz-server/`, it can be run as follows:\n\n```bash\ndocker compose restart musicbrainz\n```\n\n[Build search indexes](#set-up-search-indexes) and\n[Enable live indexing](#enable-live-indexing) are the same.\n\nReplication is not applicable to development setup.\n\nSimply restart the container when checking out a new branch.\n\n### Local development of Search Index Rebuilder\n\nThis is very similar to the above but for Search Index Rebuilder (SIR):\n\n1. Optionally set the following variables in the `.env` file:\n   - `SIR_DEV_CONFIG_PATH`\n     (Default: `./default/config.ini` replacing `SIR_CONFIG_PATH`)\n   - `SIR_DEV_LOCAL_ROOT`\n     (Default: `../sir` assuming that `musicbrainz-docker` and `sir`\n     have been cloned under the same parent directory)\n   - `SIR_DEV_PYTHON_VERSION`\n     (Default: `3.13` matching `metabrainz/python` image tag)\n   - `SIR_DEV_BASE_IMAGE_DATE`\n     (Default: `20250313` matching `metabrainz/python` image tag)\n   - `SIR_DEV_VERSION`\n     (Default: `py313-stage1` which is informative only)\n2. Run `admin/configure add sir-dev`\n3. Run `docker compose build indexer`\n4. Run `docker compose up -d`\n\nNotes:\n\n* It will override any `config.ini` file in your local working copy of SIR.\n* Requirements are being cached and will be updated on container’s startup.\n* See [how to configure SIR in `musicbrainz-docker`](#customize-search-indexer-configuration).\n\n### Local development of MusicBrainz Solr\n\nThe situation is quite different for this service as it doesn’t\ndepends on any other. Its development rather rely on schema. See\n[mb-solr](https://github.com/metabrainz/mb-solr) and\n[mmd-schema](https://github.com/metabrainz/mmd-schema).\n\nHowever, other services depend on it, so it is useful to run a local\nversion of `mb-solr` in `search` service for integration tests:\n\n1. Run `build.sh` from your `mb-solr` local working copy, which will\n   build an image of `metabrainz/mb-solr` with a local tag reflecting\n   the working tree status of your local clone of `mb-solr`.\n2. Set `MB_SOLR_VERSION` in `.env` to this local tag.\n3. Run `docker compose up -d`\n\n## Helper scripts\n\nThere are two directories with helper scripts:\n\n* [`admin/`](admin/) contains helper scripts to be run from the host.\n  For more information, use the `--help` option:\n\n  ```bash\n  admin/configure --help\n  admin/create-amqp-extension --help\n  admin/purge-message-queues --help\n  admin/set-replication-token --help\n  admin/setup-amqp-triggers --help\n  ```\n\n  See also:\n  - [Docker Compose overrides](#docker-compose-overrides) for more\n    information about `admin/configure`.\n  - [Enable live indexing](#enable-live-indexing) for more information\n    about `admin/create-amqp-extension`\n    and `admin/setup-amqp-triggers`.\n  - [Enable replication](#enable-replication) for more information\n    about `admin/set-replication-token`.\n\n* [`build/musicbrainz/scripts/`](build/musicbrainz/scripts/) contains\n  helper scripts to be run from the container attached to the service\n  `musicbrainz`. Most of these scripts are not for direct use, but\n  [createdb.sh](#create-database) and below-documented\n  [recreatedb.sh](#recreate-database).\n\n\u003c!-- TODO: add help option to build/*/scripts/* --\u003e\n\n### Recreate database\n\nIf you need to recreate the database, you will need to enter the\npostgres password set in [postgres.env](default/postgres.env):\n\n* `docker compose run --rm musicbrainz recreatedb.sh`\n\nor to fetch new data dumps before recreating the database:\n\n* `docker compose run --rm musicbrainz recreatedb.sh -fetch`\n\n### Recreate database with indexed search\n\nIf you need to recreate the database with indexed search:\n\n```bash\nadmin/configure rm replication-cron # if replication is enabled\ndocker compose stop\ndocker compose run --rm musicbrainz fetch-dump.sh indexed\nadmin/purge-message-queues\ndocker compose up -d search\ndocker compose exec search fetch-backup-archives\ndocker compose exec search load-backup-archives\n# See the note no. 1 below\ndocker compose run --rm musicbrainz recreatedb.sh\ndocker compose up -d\nadmin/setup-amqp-triggers install\nadmin/configure add replication-cron\ndocker compose up -d\n# See the note no. 2 below\n```\n\nNotes:\n1. You will need to enter the postgres password set in\n   [postgres.env](default/postgres.env) when running the command\n   `recreatedb.sh`\n2. Once you are satisfied with the search results, you can drop the fetched archive files:\n\n   ```bash\n   sudo docker-compose exec search remove-backup-archives\n   ```\n\n## Update\n\nCheck your working tree is clean with:\n\n```bash\ngit status\n```\n\nCheck your currently checked out version:\n\n```bash\ngit describe --dirty\n```\n\nCheck [releases](https://github.com/metabrainz/musicbrainz-docker/releases) for\nupdate instructions.\n\n## Cleanup\n\nEach time you are rebuilding a new image, for either updating to a new\nrelease or applying some changes in configuration, the previous image\nis not removed.\nOn the one hand, it is convenient as it allows you to quickly restore\nit in case the new image has critical issues.\nOn the other hand, it is filling your disk with some GBs over time.\nThus it is recommended to do a regular cleanup as follows.\n\n:warning: If you are using Docker for anything else than this Compose project,\nthe below command will also remove all unused images.\n\n```bash\ndocker system prune --all\n```\n\n## Removal\n\nRemoving the directory isn’t enough, the Docker objects (images,\ncontainers, volumes) have to be removed too for a complete removal.\n\nBefore removing the directory where you cloned this repository,\nrun the following command **from that directory**.\n\n```bash\ndocker compose down --remove-orphans --rmi all --volumes\n```\n\nIt will output what has been removed so that you can check it.\nOnly after it is over, you can remove the directory.\n\n## Issues\n\nIf anything doesn't work, check the [troubleshooting](TROUBLESHOOTING.md) page.\n\nIf you still don’t have a solution, please create an issue with versions info:\n\n```bash\necho MusicBrainz Docker: `git describe --always --broken --dirty --tags` \u0026\u0026 \\\necho Docker Compose: `docker compose version --short` \u0026\u0026 \\\ndocker version -f 'Docker Client/Server: {{.Client.Version}}/{{.Server.Version}}'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetabrainz%2Fmusicbrainz-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetabrainz%2Fmusicbrainz-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetabrainz%2Fmusicbrainz-docker/lists"}