Getting started¶

We provide a docker image with the full beeets-flask setup. You can run it with docker-compose or docker. We recommend using the stable tag, alternatively you may use latest for the most recent build.

Using docker compose¶

Follow these steps to quickly set up and run the Beets-Flask application using Docker.

  1. Create a new directory:

mkdir beets-flask
cd beets-flask

  1. Download the docker-compose.yaml file or create it manually and copy the content from below.

wget https://raw.githubusercontent.com/pspitzner/beets-flask/main/docker/docker-compose.yaml

If you want to create it manually, you can use the following content:

services:
    beets-flask:
        image: pspitzner/beets-flask:stable
        restart: unless-stopped
        ports:
            - "5001:5001"
        environment:
            # Change to your timezone
            TZ: "Europe/Berlin"
            # 502 is default on macos, 1000 on linux
            USER_ID: 1000
            GROUP_ID: 1000
            # Optional: Add extra groups to the beetle user for file permissions
            # Format: "group_name1:gid1,group_name2:gid2"
            # Example: EXTRA_GROUPS: "nas_shares:1001,media:1002"
        volumes:
            - /wherever/config/:/config
            # for music folders, match paths inside and out of container!
            - /music_path/inbox/:/music_path/inbox/
            - /music_path/clean/:/music_path/clean/
            # If you want to persist the logs, you can mount a logs directory
            # - /wherever/logs/:/logs

  1. Edit the docker-compose.yaml file! Please change the configuration and volume paths, otherwise the application might not start or work correctly. See the configuration section for more information.

  2. Start the application using docker-compose.

docker-compose up

The application should now be available at http://localhost:5001!

Using docker¶

Similarly, you can also run the application using docker directly. Feel free to adjust the following command to your needs.

docker run -d -p 5001:5001 \
    -e TZ=Europe/Berlin \
    -e USER_ID=1000 \
    -e GROUP_ID=1000 \
    -v /wherever/config/:/config \
    -v /music_path/inbox/:/music_path/inbox/ \
    -v /music_path/clean/:/music_path/clean/ \
    --name beets-flask \
    pspitzner/beets-flask:stable

Configuration¶

As the minimum, you need to update the information about your music folders. Edit config/beets/config.yaml to point to your music library: The config mount has to point to the same folders inside and outside the container!

# config/beets/config.yaml
# Update to your mounted music folder!
directory: /music_path/clean/

Please checkout the configuration page for more customization options and further details about the configuration files.

Use your existing beets library¶

Make a backup! Your config folder ~/.config/beets/ should be the minimum.

Mount your existing beets config folder to the container. This way you can use your existing beets library and configuration.

# docker-compose.yml
volumes:
    - ~/.config/beets/:/config/beets/
    - ~/.config/beets-flask/:/config/beets-flask/
    - /music_path/clean/:/music_path/clean/

Make sure that the library location in your beets config.yaml is either set to the path inside the container, or not specified (the default should work).

Note that /music_path/clean/ needs to be consistent inside and outside of the container. Otherwise beets will not be able to manage files correctly. For instance if your music is in /home/user/music/, you should mount with /home/user/music/:/home/user/music/.

To start from scratch or with a copy of your existing library¶

In your docker compose, mount a fresh config folder

# docker-compose.yml
volumes:
    - /music_path/config/:/config/
    - /music_path/inbox/:/music_path/inbox/
    - /music_path/imported/:/music_path/imported/

Start the container, and you will find some files placed in the mounted config folder. Then either start customizing a config here, or copy content from your ~/.config/beets/ to /music_path/config/beets/