MusicBrainz Server / Setup

MusicBrainz Server virtual machine

Running a MusicBrainz Server as a virtual machine requires some Linux knowledge, but it is vastly simpler than installing the server from scratch. (Have a look at the open issues in the bug tracker, though.) The pre-built virtual image can be imported into either VirtualBox or VMware. If you are using Amazon EC2 you can not use this virtual image and will instead have to follow the steps outlined in the source code To set up a virtual machine instance, download the torrent file and follow these steps:

MusicBrainz Server Virtual Machine (Virtual Box)
BitTorrent Download: musicbrainz-server-2017-09-07.ova.torrent
Size: 173Kb
Version: 2017-09-07

MusicBrainz Server Virtual Machine (Virtual Box)
FTP Download: musicbrainz-server-2017-09-07.ova
Size: 17.2GB Open Virtualization Archive (OVA)
Version: 2017-09-07
MD5: 89ea9652e08f6cd691fc294439996440

Running with VMware

We no longer support running our VM under VMWare, since VirtualBox has become stable enough for our needs. If you intend to run this with other VM software, we doubt it will work and we're not going to support other software.

Running with VirtualBox

Before you start, make sure you have the lastest version of VirtualBox installed.

  1. Start VirtualBox and choose Import Appliance from the File menu. Select the downloaded file.
  2. Once VirtualBox has imported the appliance, select the imported virtual machine from the list of virtual machines and click on Start.

Using the VM

  1. Once the instance has started up, log in on the console using the username vagrant and password vagrant. This account has sudo privileges -- if you would like to set a root password, you can do that via sudo.
  1. You can SSH into the machine via the port 2222 on localhost of the host OS. (e.g. ssh -p 2222 vagrant@localhost )
  2. To access the MusicBrainz web site and web service, go to: http://localhost:5000
  3. To access the Search Server web service, go to: http://localhost:8080

Resetting Docker Containers

This new VM is based on docker containers. The docker containers should start automagically at boot time, but sometimes they don't. If any of the commands listed below do not work or give you strange docker/container errors, reset the containers with this command from the VM:


Then try your command again.

Tuning your VM

We recommend that you give your VM 2GB of ram and 2 CPU cores, if that is possible. The more RAM you give to the VM, the faster it is going to run. To change the memory settings, you will need to shut down the VM, change the settings and then re-start the VM.

Running Replication

This VM comes "replication ready". To enable replication, and have the database catch up with the latest replication packets, you will need to sign up for a Live Data Feed access token on the MetaBrainz web site. Then SSH into the machine as described above then:

bin/set-token <replication token>

To start replication, do this:

bin/replicate now

This will load all of the changes to the database since the VM update. Unlike the previous versions of this VM, this command will not give you any output as it applies replication packets. If you want to see the progress, open another terminal window to the VM and then:


This will allow you to see the output of the replication packets being applied.

Automating Replication

To turn on background replication, run:

bin/replicate start

to turn it off:

bin/replicate stop

We recommend leaving replication off for the time being, until you've built search indexes for the VM.

Building search indexes

The VM comes with support to build search indexes. In order to build the indexes, log in to the account and then:


Depending on your machine, this may take quite a long time. We recommend that you leave this running overnight. After the indexes are complete, you should be able to carry out indexed searches in your VM.

Accessing the database

To access the main postgres database, you can do this:

psql -h localhost -U musicbrainz -p 15432

You'll need to install the psql postgres command line client on your host OS.

Turning the VM into development box

If you would like to use the VM to do development instead of using it as a simple database slave, you'll need to edit lib/ and set REPLICATION_TYPE to RT_STANDALONE and run admin/psql READWRITE and execute the following queries:

DELETE FROM annotation WHERE editor > (SELECT max(id) FROM editor);
DELETE FROM release_annotation WHERE NOT EXISTS (SELECT 1 FROM annotation WHERE = release_annotation.annotation);

then from the command line execute:

admin/psql READWRITE < admin/sql/CreateFKConstraints.sql
admin/psql READWRITE < admin/sql/CreateFunctions.sql

Migrating the MusicBrainz Server from a Virtual Machine to a Physical Machine

Taken from AskUbuntu.

It is possible to migrate the MusicBrainz Server image (or any virtual image) from a virtual machine onto bare metal, should you desire to.


Step 1: Converting the Disk to a Raw format

This step is included mostly for the sake of convenience. By doing some prep work on the image before writing, standard Linux tools can be used to write to and manipulate the disk afterwards. This can be done from your current host environment without booting to your LiveCD.

cd /path/to/image/ 
# for VMWare
sudo apt-get install qemu-kvm
qemu-img convert your-vmware-disk.vmdk -O raw disk.img
# For VirtualBox
VBoxManage internalcommands converttoraw your-virtualbox-disk.vdi disk.img

Option 1: Write the Image to it's Own Disk

This assumes that you're going to overwrite an entire disk. This is the most ideal situation since the server will have an entire disk to work with. If you're looking to have the image installed along side an existing operating system, skip to Option 2.

sudo dd if=/media/external/disk.img of=/dev/sdX

Option 2: Installing the Image Alongside Another OS

This is potentially safer than the above method and is very similar. Your LiveCD must be the same Ubuntu version as the virtual image.

sudo mkdir /media/oldinstall
sudo mount -o loop /media/external/disk.img /media/oldinstall
sudo rsync /media/oldinstall /media/newinstall

Changing Kernel Versions

Parts taken from the Ubuntu community documentation.

For images from 2013-08-01 and older, you will need to change the kernel flavour from -virtual to -generic. The -virtual kernel flavour is lighter, but only supports hardware typically seen in virtual environments while -generic provides support for a wider range of hardware, such as what you would see in a physical server. Both of these versions are provided in the default Ubuntu repositories.

sudo mount /dev/sdXY /mnt
sudo mount /dev/sdXZ /mnt/boot
for i in /dev /dev/pts /proc /sys /run; do sudo mount -B $i /mnt$i; done
sudo chroot /mnt
sudo apt-get install linux-image-generic linux-header-generic
sudo apt-get purge --auto-remove linux-image-virtual linux-header-virtual

Setup MusicBrainz Server from source code

This can potentially be a very laborious and time consuming method of getting a functioning MusicBrainz server. Using the virtual machine is recommended, except for development purpose.

Get a copy of musicbrainz-server from git:

git clone --recursive musicbrainz-server
cd musicbrainz-server

And follow the instructions in the INSTALL file.


The setup process may look daunting, but please don't let this discourage you; the INSTALL is thorough and contains a lot of information, and we are willing to provide assistance. If you have questions about installing, join us in the #metabrainz IRC channel or post a question on the community forum and we will attempt to help you out.

We recommend that you dive in and give it a try - who knows how far you'll get and what you might learn along the way!


In order to set up a running MusicBrainz server with the full database you will need:

As a developer the following knowledge/skills are beneficial:

Note: The server has never been ported to Windows, and we suspect that it would be a fair amount of work to make that happen.

External Links