Skip to main content
Version: Stable 4.x

Development environment

This page describes the different way to run LibreTime in a development environment.

The recommended development environment is the docker-compose setup.


To setup a docker-compose development environment, run the following commands:

# Clean and build
make clean
cp .env
DOCKER_BUILDKIT=1 docker-compose build

# Setup
make dev-certs
docker-compose run --rm legacy make build
docker-compose run --rm api libretime-api migrate

# Run
docker-compose up -d
docker-compose logs -f

You may also use the following make clean dev shortcut:

make clean dev

docker-compose logs -f


To use Vagrant, you need to install a virtualization engine: VirtualBox or Libvirt. The [vagrant-vbguest] package on Github can help maintain guest extensions on host systems using VirtualBox.


If you try run a libvirt provided box after using a VirtualBox one, you will receive an error:

Error while activating network:
Call to virNetworkCreate failed: internal error: Network is already in use by interface vboxnet0.

This is fixed by stopping virtualbox and re-creating the vagrant box:

sudo systemctl stop virtualbox
vagrant destroy focal
vagrant up focal --provider=libvirt

Installing Libvirt

On Debian and Ubuntu:

  1. Install Vagrant
sudo apt install vagrant vagrant-libvirt libvirt-daemon-system vagrant-mutate libvirt-dev
sudo usermod -aG libvirt $USER
  1. Reboot your computer, and then run
vagrant box add bento/ubuntu-20.04 --provider=virtualbox
vagrant mutate bento/ubuntu-20.04 libvirt
vagrant up focal --provider=libvirt

On other distributions, you will need to install libvirt and vagrant-mutate and then run

vagrant plugin install vagrant-libvirt
sudo usermod -a -G libvirt $USER

# Reboot

vagrant plugin install vagrant-mutate
vagrant box fetch bento/ubuntu-20.04
vagrant mutate bento/ubuntu-20.04 libvirt
vagrant up focal --provider=libvirt

Starting LibreTime Vagrant

To get started you clone the repo and run vagrant up. The command accepts a parameter to change the default provider if you have multiple installed. This can be done by appending --provider=virtualbox or --provider=libvirt as applicable.

git clone
cd libretime
vagrant up focal

If everything works out, you will find LibreTime on port 8080 and Icecast on port 8000.

Once you reach the web setup GUI you can click through it using the default values. To connect to the vagrant machine you can run vagrant ssh focal in the libretime directory.

Alternative OS installations

With the above instructions LibreTime is installed on Ubuntu Focal. The Vagrant setup offers the option to choose a different operation system according to you needs.

Ubuntu 20.04vagrant up focalInstall on Ubuntu Focal Fossa.
Debian 11vagrant up bullseyeInstall on Debian Bullseye.


If anything fails during the initial provisioning step you can try running vagrant provision to re-run the installer.

If you only want to re-run parts of the installer, use --provision-with $step. The supported steps are prepare and install.


Multipass is a tool for easily setting up Ubuntu VMs on Windows, Mac, and Linux. Similar to Docker, Multipass works through a CLI. To use, clone this repo and then create a new Multipass VM.

git clone
cd libretime
multipass launch focal -n ltTEST --cloud-init cloud-init.yaml
multipass shell ltTEST

Multipass isn't currently able to do an automated install from the cloud-init script. After you enter the shell for the first time, you will still need to run the LibreTime installer.

The IP address of your new VM can be found by running multipass list. Copy and paste it into your web browser to access the LibreTime interface and complete the setup wizard.

You can stop the VM with multipass stop ltTEST and restart with multipass start ltTEST. If you want to delete the image and start again, run multipass delete ltTEST && multipass purge.

Cloud-init options in cloud-init.yaml

You may wish to change the below fields as per your location.

timezone: America/New York # change as needed
pools: [""]
servers: ["", ""]