ampache/IDEA.md

What this image is

A self-contained Docker image for Ampache, the open-source web-based music streaming server. The image bundles the full application stack in a single Alpine Linux container: Apache 2 as the web server, PHP 8.4 via PHP-FPM for application execution, MariaDB as the relational database, and the Ampache PHP application itself pre-installed under /usr/local/share/ampache. On first run, navigating to http://localhost:80/ lands on the Ampache web installer (install.php), which provisions the database and creates the initial admin account. After installation, users can catalog and stream their music libraries, manage users and playlists, and connect media players via Ampache's API or DLNA/UPnP capabilities.

How this image is built and wired

Base image and tooling

Built from casjaysdev/alpine:latest via a multi-stage Dockerfile (build stage → FROM scratch final). tini is the PID 1 supervisor; gosu provides privilege dropping. Package management is handled by pkmgr (auto-detects apk).

Package set

All packages come from Alpine's apk package manager. Key groups:

• Apache 2: apache2 apache2-ctl apache2-utils apache2-ssl apache2-proxy apache2-http2 apache2-brotli apache2-icons apache2-error
• PHP 8.4: php84 php84-fpm plus all modules Ampache requires (pdo, pdo_mysql, mysqli, mysqlnd, session, intl, curl, simplexml, xml, xmlreader, xmlwriter, dom, mbstring, iconv, tokenizer, fileinfo, openssl, phar, gd, zip, bz2, gmp, exif, opcache, pecl-redis, ctype)
• MariaDB: mariadb mariadb-client mariadb-server-utils
• Utilities: bash tini curl wget unzip tar gzip tzdata ca-certificates pwgen

Build-time setup flow (rootfs/root/docker/setup/)

Script	Role
00-init.sh	Clears template-files/{data,config,defaults} staging dirs
01-system.sh	Stub (Alpine repos are already configured by the base image)
02-packages.sh	Stub (no post-install compile steps; prebuilt Ampache zip needs no composer/npm)
03-files.sh	Auto-installs rootfs/tmp/etc/* → /etc/* and stages copies under template-files/config/
04-users.sh	Defensive creation of apache:apache and mysql:mysql system accounts
05-custom.sh	Core setup: wipes distro defaults under /etc/{apache2,php84,my.cnf.d}/*, copies our optimized configs from /tmp/etc/, then downloads and unpacks the Ampache prebuilt zip to /usr/local/share/ampache/
06-post.sh	Stub
07-cleanup.sh	Stub

Config wipe-and-replace

05-custom.sh performs the canonical wipe-and-replace for all three config trees:

1. Preserve apache2/mime.types and apache2/magic (not shipped in our rootfs/tmp/etc/apache2/)
2. rm -Rf /etc/{apache2,php84,my.cnf.d}/*
3. cp -Rf /tmp/etc/{apache2,php84,my.cnf.d}/. /etc/{apache2,php84,my.cnf.d}/
4. Copy resulting /etc/ trees to template-files/config/ for runtime seeding

Runtime init.d scripts

Two init.d scripts run in numeric order:

09-mariadb.sh

• SERVICE_NAME="mariadb", EXEC_CMD_BIN='mariadbd'
• Runs as mysql:mysql; datadir /data/db/mariadb; socket /run/mysqld/mysqld.sock
• IS_DATABASE_SERVICE="yes", DATABASE_SERVICE_TYPE="mariadb"
• __run_pre_execute_checks: initializes the datadir with mariadb-install-db if ibdata1 is missing
• __post_execute: waits for the socket, then creates the ampache database, ampache user (random password), grants privileges, and sets the root password

99-ampache.sh

• SERVICE_NAME="ampache", EXEC_CMD_BIN='/usr/local/etc/docker/bin/start-ampache'
• IS_WEB_SERVER="yes", USES_DATABASE_SERVICE="yes", DATABASE_SERVICE_TYPE="mariadb"
• SERVICE_USER="apache", SERVICE_GROUP="apache"
• WWW_ROOT_DIR="/usr/local/share/ampache/public", ETC_DIR="/etc/apache2", CONF_DIR="/config/apache2"
• ADDITIONAL_CONFIG_DIRS="/config/php84 /config/ampache"
• __execute_prerun: creates runtime dirs (/run/apache2 /run/php-fpm /tmp/php-sessions /data/logs/{apache2,php-fpm}), chowns them to apache:apache; symlinks ampache.cfg.php between /usr/local/share/ampache/config/ and /config/ampache/ once install.php writes it
• __run_pre_execute_checks: waits up to 30 s for the MariaDB socket; validates httpd -t apache config syntax
• __update_conf_files: replaces the REPLACE_TZ token in /etc/php84/php.ini with $TZ
• __post_execute: mirrors ampache.cfg.php out to /config/ampache/ and creates the symlink if install.php has written it

start-ampache wrapper

EXEC_CMD_BIN points to /usr/local/etc/docker/bin/start-ampache, which:

1. Starts php-fpm84 in the background (waits up to 10 s for /run/php-fpm/php-fpm.sock)
2. Exec's httpd -D FOREGROUND -f /etc/apache2/httpd.conf (becomes the process the framework monitors)

Config paths

Component	Config file	User-editable at
Apache main	/etc/apache2/httpd.conf	/config/apache2/httpd.conf
Apache ampache vhost	/etc/apache2/conf.d/ampache.conf	/config/apache2/conf.d/ampache.conf
Apache MPM tuning	/etc/apache2/conf.d/mpm.conf	/config/apache2/conf.d/mpm.conf
User vhosts	IncludeOptional /config/apache2/vhosts.d/*.conf	/config/apache2/vhosts.d/
PHP runtime	/etc/php84/php.ini	/config/php84/php.ini
PHP-FPM global	/etc/php84/php-fpm.conf	/config/php84/php-fpm.conf
PHP-FPM pool	/etc/php84/php-fpm.d/www.conf	/config/php84/php-fpm.d/www.conf
MariaDB server	/etc/my.cnf.d/mariadb-server.cnf	/config/my.cnf.d/mariadb-server.cnf
Ampache app config	/usr/local/share/ampache/config/ampache.cfg.php	/config/ampache/ampache.cfg.php (symlinked)

Volume layout

• /config — all user-editable configs (seeded on first run from template-files/config/)
• /data — MariaDB datadir (/data/db/mariadb), logs (/data/logs/), media library if mounted

Port

• 80 (HTTP); 443 available if SSL is enabled via /config/enable/ssl