{"id":22728490,"url":"https://github.com/6arms1leg/mpd-docker","last_synced_at":"2026-05-16T17:04:08.264Z","repository":{"id":253685470,"uuid":"362592911","full_name":"6arms1leg/mpd-docker","owner":"6arms1leg","description":"A home audio, local playback MPD Docker image with UID/GID handling, based on Alpine Linux","archived":false,"fork":false,"pushed_at":"2021-04-29T19:51:14.000Z","size":68,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-30T00:27:26.459Z","etag":null,"topics":["docker","docker-compose","mpd"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/6arms1leg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2021-04-28T20:05:11.000Z","updated_at":"2025-03-21T13:43:50.000Z","dependencies_parsed_at":"2024-08-18T19:42:01.979Z","dependency_job_id":"2196d326-180b-435a-8344-dcb96739a85c","html_url":"https://github.com/6arms1leg/mpd-docker","commit_stats":null,"previous_names":["6arms1leg/mpd-docker"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/6arms1leg/mpd-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/6arms1leg%2Fmpd-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/6arms1leg%2Fmpd-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/6arms1leg%2Fmpd-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/6arms1leg%2Fmpd-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/6arms1leg","download_url":"https://codeload.github.com/6arms1leg/mpd-docker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/6arms1leg%2Fmpd-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280902224,"owners_count":26410744,"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-10-25T02:00:06.499Z","response_time":81,"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","mpd"],"created_at":"2024-12-10T17:16:20.560Z","updated_at":"2025-10-25T04:10:54.179Z","avatar_url":"https://github.com/6arms1leg.png","language":"Makefile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MPD (Docker)\n\nA home audio, local playback MPD Docker image with UID/GID handling, based on\nAlpine Linux.\n\n*The [Quickstart section](#quickstart) shows the fastest way to set everything\nup without providing further details.*\n\nThis MPD Docker image setup plays back audio files locally, streaming audio\ndirectly to the Docker host machines’ sound card.  \nThis Docker image is not designed for network streaming.  \nClients (usually users within the same LAN as the Docker host machine) can\ninteract with MPD using one of the many MPD software clients available.\nWithin the Docker container the MPD server is executed by an `mpd` user, whos\nUID/GID is specified at container start.  \nThe UML deployment diagram in the figure below gives an overview.\n\n![UML deployment diagram](./uml-dd-deployment-overview.png \"UML deployment diagram\")\n\n\u003e Used terminology in this documentation:\n\u003e * Client - Client machine that connects to the host\n\u003e * Host - Host machine that runs the Docker container\n\n\u003e Used variables in this documentation:\n\u003e * `MPD_BASE_PATH` - Path to the directory that contains this project’s files\n\u003e   (especially `Dockerfile` + other build-related files and\n\u003e   `docker-compose.yml`)\n\u003e * `MPD_GID` - GID assigned to the `mpd` user within the Docker container,\n\u003e   e.g. `1000`.\n\u003e   The access permissions of the content created in the Docker volumes will be\n\u003e   set to this GID.\n\u003e * `MPD_PORT` - Network port used for the MPD connection (to control the MPD\n\u003e   music server), e.g. `6600`\n\u003e * `MPD_UID` - UID assigned to the `mpd` user within the Docker container,\n\u003e   e.g. `1000`.\n\u003e   The access permissions of the content created in the Docker volumes will be\n\u003e   set to this UID.\n\u003e * `MPD_MUSIC_DIR_SUBPATH` - A path relative to MPD’s music directory\n\u003e * `MUSIC_DIR` - An audio file directory name on the host\n\u003e * `VERSION` - Version of this project, e.g. `1.0.0`.\n\u003e   Adheres to [Semantic Versioning](https://semver.org).\n\n## Quickstart\n\n**How to** set everything up the fastest way possible:\n\nStep 1:\n\n```sh\n$ cd ${MPD_BASE_PATH}\n$ make build\n$ make prepare-deploy\n```\n\n... and adjust `docker-compose.yml` and `mpd/mpd.conf`.\n\nStep 2:\n\n```sh\n$ make deploy\n$ make database-update\n```\n\n... and wait for the MPD database update to finish.\n\n\u003e Use `make show-status` to query MPD’s database update status.\n\n## Applicability\n\nThe main use case for this project is to provide an MPD music server that plays\naudio files locally on the home audio loudspeakers, streaming audio only to the\nhost’s sound card.\nClients connected to MPD over a network (usually LAN) can control the local\nplayback of audio files.\n\n*This project is not intended for streaming audio files over a network.*\n\n## Requirements\n\nFor basic usage (mandatory):\n* Docker\n\nFor easy handling (recommended):\n* Docker Compose\n* Make\n\n## Makefile\n\nMost of the instructions in this documentation can also be run with the\nprovided `Makefile` (which uses Docker Compose).\nRun `cd ${MPD_BASE_PATH} \u0026\u0026 make help` to see the list of available targets.\n\n\u003e The Makefile uses Docker Compose, see the prerequisite in \"How to run the\n\u003e container with Docker Compose\" in the [Run section](#run).\n\n## Build\n\n**How to** build the Docker image:\n\n```sh\n$ cd ${MPD_BASE_PATH}\n$ sudo docker build -t mpd:${VERSION} .\n$ sudo docker image tag mpd:${VERSION} mpd:latest\n```\n\n## Arguments\n\n* Exposed port: `6600`\n* Volumes:\n    * `/mpd/mpd.conf`: Volume that only holds MPD’s configuration file\n    * `/mpd/.mpd/`: Volume to store MPD’s work files\n    * `/mpd/music/`: Volume that maps locally stored audio files into MPD’s\n      music directory\n* Devices:\n    * `/dev/snd/`: Device (audio sink) to which MPD streams audio\n* Environment variables:\n    * `PUID`: UID that is assigned to the `mpd` user inside the Docker container\n    * `PGID`: GID that is assigned to the `mpd` user inside the Docker container\n\n\u003e Symlinks do not work with Docker.  To map (i.e., link) multiple audio file\n\u003e locations into MPD’s music directory (`/mpd/music/`) create each as a\n\u003e seperate Docker volume (mounted in its own directory under `/mpd/music/`),\n\u003e e.g., `[...]/${MUSIC_DIR}:/mpd/music/${MUSIC_DIR}/`.\n\n## Run\n\nPrerequisite:\nCopy `mpd.conf.template` to `mpd/mpd.conf` and adjust it.\n\n\u003e The MPD configuration file only contains the bare minimum of settings\n\u003e necessary to run MPD.\n\u003e You can change these settings and add new ones but mind the non-modifiable\n\u003e settings at the end of this file.\n\u003e For available options see\n\u003e [MPD User’s Manual](https://www.musicpd.org/doc/html/user.html#configuration)\n\u003e and the vanilla `/etc/mpd.conf` file inside the Docker container.\n\u003e The latter can be retrieved with\n\u003e `sudo docker run --rm mpd:latest cat /etc/mpd.conf \u003e ${MPD_BASE_PATH}/mpd/mpd.conf.template-vanilla`.\n\n**How to** run the Docker container:\n\n```sh\n$ cd ${MPD_BASE_PATH}\n$ mkdir -p ./mpd/mpd/playlists/ ./mpd/music/\n$ sudo docker run \\\n  -d \\\n  -p ${MPD_PORT}:6600 \\\n  -v ${MPD_BASE_PATH}/mpd/mpd.conf:/mpd/mpd.conf:ro \\\n  -v ${MPD_BASE_PATH}/mpd/mpd/:/mpd/.mpd/ \\\n  -v ${MPD_BASE_PATH}/mpd/music/:/mpd/music/:ro \\\n  --device /dev/snd/:/dev/snd/ \\\n  -e PUID=${MPD_UID} \\\n  -e PGID=${MPD_GID} \\\n  --cap-add SYS_NICE \\\n  --name=\"mpd\" \\\n  mpd:latest\n```\n\n**How to** run the container with Docker Compose:\n\nPrerequisite:\nCopy `docker-compose.yml.template` to `docker-compose.yml` and adjust it.\n\n\u003e Instead of modifying `docker-compose.yml` after copying it, one can create an\n\u003e `.env` file that provides the necessary variables:\n\u003e\n\u003e ```sh\n\u003e MPD_PORT=\n\u003e MPD_BASE_PATH=\n\u003e MPD_UID=\n\u003e MPD_GID=\n\u003e ```\n\u003e\n\u003e This works only as long as there is only one audio file location on the host.\n\u003e ALso see the [Arguments section](#arguments) for more details.\n\n```sh\n$ cd ${MPD_BASE_PATH}\n$ mkdir -p ./mpd/mpd/playlists/ ./mpd/music/\n$ sudo docker-compose up -d\n```\n\n## Basic usage\n\nTo use all of of mpc’s functionality, enter the Docker container interactively\nand run `mpc` there:\n\n```sh\n$ sudo docker exec -it -u mpd mpd ash\n$ mpc [...]\n```\n\n\u003e Or with Docker Compose:\n\u003e `sudo docker-compose exec -u mpd mpd ash`\n\n\u003e All \"how to\"s below can also be run interactively this way.\n\u003e In particular, this has the advantage of autocompletion of paths within MPD’s\n\u003e music directory for, e.g., adding music or partially updating MPD’s database.\n\n**How to** update MPD’s database:\n\n\u003e This functionality is usually also provided on the client.\n\n```sh\n$ sudo docker exec -u mpd mpd mpc update\n```\n\n\u003e Or with Docker Compose:\n\u003e `sudo docker-compose exec -u mpd mpd mpc update`\n\n\u003e To debug or (after the initial MPD database update) to update only a certain\n\u003e path within MPD’s music directory see \"How to partially update MPD’s\n\u003e database\" in the [Troubleshooting section](#troubleschooting)).\n\n**How to** querry MPD’s status:\n\n```sh\n$ sudo docker exec -u mpd mpd mpc status\n```\n\n\u003e Or with Docker Compose:\n\u003e `sudo docker-compose exec -u mpd mpd mpc status`\n\n## Troubleshooting\n\n**How to** show MPD’s log (STDOUT/STDERR messages):\n\n```sh\n$ sudo docker logs -t -f mpd\n```\n\n**How to** partially update MPD’s database:\n\n\u003e This can be useful to debug MPD database update issues, e.g., locating an\n\u003e offending audio file with corrupted ID3 tags that causes the update to fail.\n\u003e Also see \"How to show MPD’s log (STDOUT/STDERR messages)\".\n\n```sh\n$ sudo docker exec -u mpd mpd mpc update ${MPD_MUSIC_DIR_SUBPATH}\n```\n\n\u003e Or with Docker Compose:\n\u003e `sudo docker-compose exec -u mpd mpd mpc update ${MPD_MUSIC_DIR_SUBPATH}`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F6arms1leg%2Fmpd-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F6arms1leg%2Fmpd-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F6arms1leg%2Fmpd-docker/lists"}